Merge branch 'v3.0' into behat-formatter-cookbook

.github/workflows/build.yml

@@ -0,0 +1,29 @@
+name: Build Docs
+
+on:
+  push:
+    branches: [v3.0]
+  pull_request: ~
+
+jobs:
+  build-docs:
+    name: Build Docs
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run build command
+        run: docker compose run --rm read-the-docs-builder
+
+      - name: Check build
+        run: cat _build/html/guides.html
+
+      - name: save site as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: _build/html

.github/workflows/check.yml

@@ -0,0 +1,31 @@
+name: Check Docs
+
+on:
+  push:
+    branches: [v3.0]
+  pull_request: null
+
+jobs:
+  sphinx:
+    name: Sphinx reStructuredText validity
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install sphinx-lint
+        run: |
+          pip install --user sphinx-lint
+      - name: Check Sphinx document sources
+        run: |
+          git ls-files --cached -z -- '*.rst' \
+            | xargs --null -- python -m sphinxlint --enable all --max-line-length 120
+
+  typos:
+    name: Typos
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Search for misspellings
+        uses: crate-ci/typos@master

.readthedocs.yaml

@@ -0,0 +1,25 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    # Note: Update the Dockerfile if the python version changes
+    python: "3.12"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: conf.py
+  # Fail on all warnings to avoid broken references
+  fail_on_warning: true
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: requirements.txt

.typos.toml

@@ -0,0 +1,9 @@
+[files]
+extend-exclude = [
+    ".git/",
+]
+ignore-hidden = false
+
+[default.extend-identifiers]
+# Typos
+"Github" = "GitHub"

Dockerfile

@@ -0,0 +1,7 @@
+FROM python:3.12
+
+WORKDIR /workspace
+
+COPY requirements.txt .
+RUN python -m pip install --upgrade --no-cache-dir pip setuptools
+RUN python -m pip install --upgrade --no-cache-dir -r requirements.txt

README.md

@@ -0,0 +1,55 @@
+# Documentation & web content for docs.behat.org
+
+This repo holds the content for https://docs.behat.org/, which is built and hosted on [Read the Docs Community](https://about.readthedocs.com/) (RtD).
+https://behat.org and https://www.behat.org both redirect to this site.
+
+At the moment, RtD does not feed build status back to GitHub for builds on a project's main branch(es). Instead, you
+can find build history for each version on RtD.
+
+| Version | Status                                                                                                                                                                        | Docs URL                          | Build dashboard                                                                                   |
+|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------|---------------------------------------------------------------------------------------------------|
+| v2.5    | [![Documentation Status](https://readthedocs.org/projects/behat/badge/?version=v2.5&style=for-the-badge)](https://docs.behat.org/en/latest/?badge=v2.5)                       | https://docs.behat.org/en/v2.5/   | [v2.5 build history](https://app.readthedocs.org/projects/behat/builds/?version__slug=v2.5)       |
+| v3.0    | [![Documentation Status](https://readthedocs.org/projects/behat/badge/?version=v3.0&style=for-the-badge)](https://docs.behat.org/en/latest/?badge=v3.0)                       | https://docs.behat.org/en/v3.0/   | [v3.0 build history](https://app.readthedocs.org/projects/behat/builds/?version__slug=v3.0)       |
+| latest* | [![Documentation Status](https://readthedocs.org/projects/behat/badge/?version=latest&style=for-the-badge)](https://docs.behat.org/en/latest/?badge=v3.0&style=for-the-badge) | https://docs.behat.org/en/latest/ | ["latest" build history](https://app.readthedocs.org/projects/behat/builds/?version__slug=latest) |
+
+> \* the "latest" version is currently also based off the v3.0 branch, but is a separate build on RTD.
+
+## Project structure
+
+The site is built using [sphinx](https://www.sphinx-doc.org/en/master/index.html), a python-based documentation
+generator based on reStructuredText (.rst) or MyST Markdown (.md) files. Most content is populated in these files.
+
+reStructuredText is similar to Markdown, with some differences. The following resources may be useful:
+
+* RtD's [Getting started with RST tutorial](https://sphinx-tutorial.readthedocs.io/step-1/)
+* The [Spinx reStructuredText primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)
+* @waldyrious' [browser-based RST playground](https://waldyrious.net/rst-playground/)
+
+Sphinx takes these .rst/.md source files and renders them into the final HTML site with the custom `borg` theme. You'll
+find the templates and resources for this under the `_themes/borg` directory. The theme provides the overall page
+layout, as well as features such as automatic contents pages and navigation.
+
+## Previewing on GitHub
+
+The GitHub web interface natively supports rendering both reStructuredText and Markdown files. For simple changes, this
+is often the quickest way to check the formatting of your contribution. Custom sphinx tags & metadata (including some
+navigation tags & internal links) will not be rendered, but the main content should appear roughly as it will in the
+built version.
+
+## Building locally
+
+For more significant changes, you may want to build the full docs site locally. For this, you will need python, sphinx
+and the relevant dependencies. The easiest solution may be to use a temporary docker container. In this repository you will
+find a `Dockerfile` and a `docker-compose.yml` file that will let you do that easily
+
+```bash
+# Launch a docker container with the right dependencies and run the site build command
+# This will build the container if needed, using the Dockerfile
+docker compose run --rm read-the-docs-builder
+
+# The docs will be generated into _build/html
+# Check the CLI output for any errors
+```
+
+If you encounter problems, start by looking at the logs of the latest build on Read the Docs to see the commands that
+were executed. It's possible that this README has got out of date with later changes to the build process.

_themes/borg/layout.html

@@ -15,8 +15,8 @@
     <header class="clearfix">
         <div class="header-center">
             <a href="{{ pathto('index') }}"><img class="nav-logo" src="{{ pathto('_static/images/[email protected]', 1) }}"></a>
-            <nav class="clearfix">
-                    <a class="section {% if pagename == 'guides' %}active{% endif %}" href="{{ pathto('guides') }}">
+            <nav>
+                <a class="section {% if pagename == 'guides' %}active{% endif %}" href="{{ pathto('guides') }}">
                     Guides
                 </a>
                 <a class="section {% if pagename == 'community' %}active{% endif %}"
@@ -27,10 +27,15 @@
                    href="https://github.com/search?o=desc&q=behat+extension+in%3Aname%2Cdescription&ref=searchresults&s=stars&type=Repositories&utf8=%E2%9C%93">
                     Extensions
                 </a>
-                <a class="section" href="https://github.com/Behat/Behat/blob/master/CHANGELOG.md#change-log">
+                <a class="section {% if pagename == 'releases' %}active{% endif %}"
+                   href="{{ pathto('releases') }}">
                     Releases
                 </a>
-                <a class="fork-us" href="https://github.com/Behat/Behat">GitHub</a>
+                <div class="section search" role="search">
+                    <label class="sr-only o" for="searchbox">Search documentation</label>
+                    <input id="searchbox" type="search" placeholder="Search…">
+                </div>
+                <a class="section fork-us" href="https://github.com/Behat/Behat">GitHub</a>
             </nav>
         </div>
     </header>
@@ -47,5 +52,13 @@
         </div>
     </footer>
 
+    <script>
+        // Trigger the Read the Docs Addons Search modal when clicking on "Search docs" input from the topnav.
+        document.querySelector("[role='search'] input").addEventListener("focusin", () => {
+            const event = new CustomEvent("readthedocs-search-show");
+            document.dispatchEvent(event);
+        });
+    </script>
+
 </body>
 </html>

_themes/borg/static/css/documentation.css

@@ -218,7 +218,8 @@ body > section {
 .text .note,
 .text .sidebar,
 .text .tip,
-.text img {
+.text img,
+table.docutils {
   margin-bottom: 20px;
 }
 
@@ -493,3 +494,25 @@ body > section {
 .text .next dt, .text .next dd {
   text-align: right;
 }
+
+table.docutils {
+  width: 100%;
+  border-collapse: collapse;
+}
+
+table.docutils th {
+    font-weight: 600;
+}
+
+table.docutils th, table.docutils td {
+  padding: 6px 13px;
+  border: 1px solid #d1d9e0;
+}
+
+table.docutils tr:nth-child(2n) {
+  background-color: #f6f8fa;
+}
+
+table.docutils td > p, table.docutils th > p {
+  margin-bottom: 0;
+}

_themes/borg/static/css/layout.css

@@ -44,11 +44,12 @@ header nav {
   z-index: 30;
   width: 654px;
   height: 68px;
+  display: flex;
+  flex-wrap: nowrap;
 }
 
 header nav .section {
   display: block;
-  float: left;
   height: 67px;
   min-height: 20px;
   padding-top: 21px;
@@ -72,22 +73,24 @@ header nav a:hover {
   border-top-color: #858585;
 }
 
-header nav .fork-us {
+header nav .section.search {
+  flex-grow: 1;
+  flex-shrink: 1;
+}
+
+header nav .section.search input {
+    box-sizing: border-box;
+    width: 100%;
+    border-radius: 10px;
+    padding: 2px 5px;
+}
+
+header nav .section.fork-us {
   display: block;
-  float: right;
-  height: 67px;
-  min-height: 20px;
-  padding-top: 21px;
   padding-left: 22px;
-  border-top: 6px solid rgb(161, 159, 159);
   background: url('../images/[email protected]') no-repeat left center;
   background-size: 15px 20px;
-  font-size: 1.4rem;
-  font-weight: 400;
-  line-height: 1.38;
   text-align: right;
-  color: rgb(80, 80, 80);
-  text-transform: uppercase;
 }
 
 .page {
@@ -150,3 +153,15 @@ footer .copyright {
   line-height: 1.38;
   color: rgb(192, 192, 192);
 }
+
+.sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border-width: 0;
+}

community.rst

@@ -3,7 +3,8 @@ Community
 
 Behat has an amazing community around it.
 
-The Behat community is friendly and welcoming. All questions and comments are valuable, so please come join the discussion!
+The Behat community is friendly and welcoming. All questions and comments are
+valuable, so please come join the discussion!
 
 There are a number of places to connect with community members at all experience levels.
 

conf.py

@@ -5,7 +5,11 @@
 from pygments.lexers.web import PhpLexer
 
 lexers['php'] = PhpLexer(startinline=True)
-extensions = []
+extensions = [
+   'notfound.extension',
+   # Enables automatic linking to headings within the document within Sphinx
+   'sphinx.ext.autosectionlabel'
+]
 
 source_suffix = '.rst'
 source_encoding = 'utf-8'
@@ -22,5 +26,6 @@
 
 htmlhelp_basename = 'behat'
 
+html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/")
 html_theme_path = ["_themes"]
 html_theme = 'borg'

cookbooks.rst

@@ -4,6 +4,7 @@ Cookbooks
 .. toctree::
    :maxdepth: 2
 
-   cookbooks/integrating_symfony2_with_behat
    cookbooks/accessing_contexts_from_each_other
+   cookbooks/creating_a_context_configuration_extension
    cookbooks/custom_formatter
+