Use rstcheck to "lint" the README (#17367)

Follow up to https://github.com/element-hq/synapse/pull/17363, so we can
detect issues with the RST file early on.


### Pull Request Checklist

<!-- Please read
https://element-hq.github.io/synapse/latest/development/contributing_guide.html
before submitting your pull request -->

* [x] Pull request is based on the develop branch
* [x] Pull request includes a [changelog
file](https://element-hq.github.io/synapse/latest/development/contributing_guide.html#changelog).
The entry should:
- Be a short description of your change which makes sense to users.
"Fixed a bug that prevented receiving messages from other servers."
instead of "Moved X method from `EventStore` to `EventWorkerStore`.".
  - Use markdown where necessary, mostly for `code blocks`.
  - End with either a period (.) or an exclamation mark (!).
  - Start with a capital letter.
- Feel free to credit yourself, by adding a sentence "Contributed by
@github_username." or "Contributed by [Your Name]." to the end of the
entry.
* [x] [Code
style](https://element-hq.github.io/synapse/latest/code_style.html) is
correct
(run the
[linters](https://element-hq.github.io/synapse/latest/development/contributing_guide.html#run-the-linters))

1 files changed, 20 insertions, 0 deletions

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index cdd881fbe1..2cc5a525a6 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -21,6 +21,7 @@ jobs:
       trial: ${{ !startsWith(github.ref, 'refs/pull/') || steps.filter.outputs.trial }}
       integration: ${{ !startsWith(github.ref, 'refs/pull/') || steps.filter.outputs.integration }}
       linting: ${{ !startsWith(github.ref, 'refs/pull/') || steps.filter.outputs.linting }}
+      linting_readme: ${{ !startsWith(github.ref, 'refs/pull/') || steps.filter.outputs.linting_readme }}
     steps:
     - uses: dorny/paths-filter@v3
       id: filter
@@ -72,6 +73,9 @@ jobs:
             - 'pyproject.toml'
             - 'poetry.lock'
             - '.github/workflows/tests.yml'
+          
+          linting_readme:
+            - 'README.rst'
 
   check-sampleconfig:
     runs-on: ubuntu-latest
@@ -269,6 +273,20 @@ jobs:
 
       - run: cargo fmt --check
 
+  # This is to detect issues with the rst file, which can otherwise cause issues
+  # when uploading packages to PyPi.
+  lint-readme:
+    runs-on: ubuntu-latest
+    needs: changes
+    if: ${{ needs.changes.outputs.linting_readme == 'true' }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - run: "pip install rstcheck"
+      - run: "rstcheck --report-level=WARNING README.rst"
+
   # Dummy step to gate other tests on without repeating the whole list
   linting-done:
     if: ${{ !cancelled() }} # Run this even if prior jobs were skipped
@@ -284,6 +302,7 @@ jobs:
       - lint-clippy
       - lint-clippy-nightly
       - lint-rustfmt
+      - lint-readme
     runs-on: ubuntu-latest
     steps:
       - uses: matrix-org/done-action@v2
@@ -301,6 +320,7 @@ jobs:
             lint-clippy
             lint-clippy-nightly
             lint-rustfmt
+            lint-readme
 
 
   calculate-test-jobs: