CI: Lint docs (#7479)

Co-authored-by: Greg Korba <greg@codito.dev>

.github/workflows/sphinx.yml

@@ -0,0 +1,37 @@
+name: Sphinx
+
+on:
+  pull_request:
+    paths:
+      - "**/*.rst"
+  push:
+    paths:
+      - "**/*.rst"
+
+permissions:
+  contents: "read"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  sphinx:
+    name: Sphinx reStructuredText validity
+    runs-on: ubuntu-latest
+    timeout-minutes: 1
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Cache pip
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-sphinx-lint
+      - 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 --disable trailing-whitespace --max-line-length 2000

doc/config.rst

@@ -76,7 +76,7 @@ Note that ``exclude`` will work only for directories, so if you need to exclude
 Both ``exclude`` and ``notPath`` methods accept only relative paths to the ones defined with the ``in`` method, can be called multiple times and accept string or array of them.
 
 See `Symfony\\Finder <https://symfony.com/doc/current/components/finder.html#location>`_
-online documentation for other `Finder` methods.
+online documentation for other ``Finder`` methods.
 
 Configuring rules
 -----------------

doc/cookbook_fixers.rst

@@ -36,7 +36,7 @@ Step by step
 ------------
 
 For this step-by-step, we are going to create a simple fixer that
-removes all comments from the code that are preceded by `;` (semicolon).
+removes all comments from the code that are preceded by ``;`` (semicolon).
 
 We are calling it ``remove_comments`` (code name), or,
 ``RemoveCommentsFixer`` (class name).

doc/ruleSets/PER-CS1.0.rst

@@ -2,7 +2,7 @@
 Rule set ``@PER-CS1.0``
 =======================
 
-**This ruleset is deprecated** in favour of `@PER-CS2.0`.
+**This ruleset is deprecated** in favour of ``@PER-CS2.0``.
 
 Rules that follow `PER Coding Style 1.0 <https://www.php-fig.org/per/coding-style/>`_.
 

doc/ruleSets/PER-CS1.0Risky.rst

@@ -2,7 +2,7 @@
 Rule set ``@PER-CS1.0:risky``
 =============================
 
-**This ruleset is deprecated** in favour of `@PER-CS2.0:risky`.
+**This ruleset is deprecated** in favour of ``@PER-CS2.0:risky``.
 
 Rules that follow `PER Coding Style 1.0 <https://www.php-fig.org/per/coding-style/>`_. This set contains rules that are risky.
 

doc/rules/whitespace/indentation_type.rst

@@ -17,7 +17,7 @@ Example #1
     <?php
 
     if (true) {
-   -	echo 'Hello!';
+   -<TAB>echo 'Hello!';
    +    echo 'Hello!';
     }
 

doc/usage.rst

@@ -42,7 +42,7 @@ which will use the intersection of the paths from the config file and from the a
 
     php php-cs-fixer.phar fix --path-mode=intersection /path/to/dir
 
-The ``--format`` option for the output format. Supported formats are ``txt`` (default one), ``checkstyle``, ``gitlab``, ``json``, ``junit``and ``xml``.
+The ``--format`` option for the output format. Supported formats are ``txt`` (default one), ``checkstyle``, ``gitlab``, ``json``, ``junit`` and ``xml``.
 
 NOTE: the output for the following formats are generated in accordance with schemas
 
@@ -96,7 +96,7 @@ Complete configuration for rules can be supplied using a ``json`` formatted stri
 
     php php-cs-fixer.phar fix /path/to/project --rules='{"concat_space": {"spacing": "none"}}'
 
-The ``--dry-run`` flag will run the fixer without making changes to your files (implicitly set when you use `check` command).
+The ``--dry-run`` flag will run the fixer without making changes to your files (implicitly set when you use ``check`` command).
 
 The ``--diff`` flag can be used to let the fixer output all the changes it makes in ``udiff`` format.
 
@@ -123,7 +123,7 @@ automatically fix anything:
 
     cat foo.php | php php-cs-fixer.phar fix --diff -
 
-Finally, if you don't need BC kept on CLI level, you might use `PHP_CS_FIXER_FUTURE_MODE` to start using options that
+Finally, if you don't need BC kept on CLI level, you might use ``PHP_CS_FIXER_FUTURE_MODE`` to start using options that
 would be default in next MAJOR release and to forbid using deprecated configuration:
 
 .. code-block:: console

src/Documentation/FixerDocumentGenerator.php

@@ -245,6 +245,8 @@ final class FixerDocumentGenerator
             {$fileName}
             RST;
 
+        $doc = str_replace("\t", '<TAB>', $doc);
+
         return "{$doc}\n";
     }
 

src/RuleSet/Sets/PERCS1x0RiskySet.php

@@ -43,7 +43,7 @@ final class PERCS1x0RiskySet extends AbstractRuleSetDescription
     public function getDescription(): string
     {
         return <<<'DESC'
-            **This ruleset is deprecated** in favour of `@PER-CS2.0:risky`.
+            **This ruleset is deprecated** in favour of ``@PER-CS2.0:risky``.
 
             Rules that follow `PER Coding Style 1.0 <https://www.php-fig.org/per/coding-style/>`_.
             DESC;

src/RuleSet/Sets/PERCS1x0Set.php

@@ -43,7 +43,7 @@ final class PERCS1x0Set extends AbstractRuleSetDescription
     public function getDescription(): string
     {
         return <<<'DESC'
-            **This ruleset is deprecated** in favour of `@PER-CS2.0`.
+            **This ruleset is deprecated** in favour of ``@PER-CS2.0``.
 
             Rules that follow `PER Coding Style 1.0 <https://www.php-fig.org/per/coding-style/>`_.
             DESC;