Add developer documentation for the Federation Sender and add a documentation mechanism using Sphinx.

.ci/scripts/prepare_old_deps.sh

@@ -35,9 +35,9 @@ sed -i \
 # compatible (as far the package metadata declares, anyway); pip's package resolver
 # is more lax.
 #
-# Rather than `poetry install --no-dev`, we drop all dev dependencies from the
-# toml file. This means we don't have to ensure compatibility between old deps and
-# dev tools.
+# Rather than `poetry install --no-dev`, we drop all dev dependencies and the dev-docs
+# group from the toml file. This means we don't have to ensure compatibility between
+# old deps and dev tools.
 
 pip install toml wheel
 
@@ -47,6 +47,7 @@ with open('pyproject.toml', 'r') as f:
  data = toml.loads(f.read())
 
 del data['tool']['poetry']['dev-dependencies']
+del data['tool']['poetry']['group']['dev-docs']
 
 with open('pyproject.toml', 'w') as f:
  toml.dump(data, f)

.github/workflows/docs.yaml

@@ -13,25 +13,10 @@ on:
  workflow_dispatch:
 
 jobs:
- pages:
- name: GitHub Pages
+ pre:
+ name: Calculate variables for GitHub Pages deployment
  runs-on: ubuntu-latest
  steps:
- - uses: actions/checkout@v3
-
- - name: Setup mdbook
- uses: peaceiris/actions-mdbook@adeb05db28a0c0004681db83893d56c0388ea9ea # v1.2.0
- with:
- mdbook-version: '0.4.17'
-
- - name: Build the documentation
- # mdbook will only create an index.html if we're including docs/README.md in SUMMARY.md.
- # However, we're using docs/README.md for other purposes and need to pick a new page
- # as the default. Let's opt for the welcome page instead.
- run: |
- mdbook build
- cp book/welcome_and_overview.html book/index.html
-
  # Figure out the target directory.
  #
  # The target directory depends on the name of the branch
@@ -55,11 +40,65 @@ jobs:
 
  # finally, set the 'branch-version' var.
  echo "branch-version=$branch" >> "$GITHUB_OUTPUT"
-
+ outputs:
+ branch-version: ${{ steps.vars.outputs.branch-version }}
+
+################################################################################
+ pages-docs:
+ name: GitHub Pages
+ runs-on: ubuntu-latest
+ needs:
+ - pre
+ steps:
+ - uses: actions/checkout@v3
+
+ - name: Setup mdbook
+ uses: peaceiris/actions-mdbook@adeb05db28a0c0004681db83893d56c0388ea9ea # v1.2.0
+ with:
+ mdbook-version: '0.4.17'
+
+ - name: Build the documentation
+ # mdbook will only create an index.html if we're including docs/README.md in SUMMARY.md.
+ # However, we're using docs/README.md for other purposes and need to pick a new page
+ # as the default. Let's opt for the welcome page instead.
+ run: |
+ mdbook build
+ cp book/welcome_and_overview.html book/index.html
+
  # Deploy to the target directory.
  - name: Deploy to gh pages
  uses: peaceiris/actions-gh-pages@bd8c6b06eba6b3d25d72b7a1767993c0aeee42e7 # v3.9.2
  with:
  github_token: ${{ secrets.GITHUB_TOKEN }}
  publish_dir: ./book
- destination_dir: ./${{ steps.vars.outputs.branch-version }}
+ destination_dir: ./${{ needs.pre.outputs.branch-version }}
+
+################################################################################
+ pages-devdocs:
+ name: GitHub Pages (developer docs)
+ runs-on: ubuntu-latest
+ needs:
+ - pre
+ steps:
+ - uses: action/checkout@v3
+
+ - name: "Set up Sphinx"
+ uses: matrix-org/setup-python-poetry@v1
+ with:
+ python-version: "3.x"
+ poetry-version: "1.3.2"
+ groups: "dev-docs"
+ extras: ""
+
+ - name: Build the documentation
+ run: |
+ cd dev-docs
+ poetry run make html
+
+ # Deploy to the target directory.
+ - name: Deploy to gh pages
+ uses: peaceiris/actions-gh-pages@bd8c6b06eba6b3d25d72b7a1767993c0aeee42e7 # v3.9.2
+ with:
+ github_token: ${{ secrets.GITHUB_TOKEN }}
+ publish_dir: ./dev-docs/_build/html
+ destination_dir: ./dev-docs/${{ needs.pre.outputs.branch-version }}

.gitignore

@@ -53,6 +53,7 @@ __pycache__/
 /coverage.*
 /dist/
 /docs/build/
+/dev-docs/_build/
 /htmlcov
 /pip-wheel-metadata/
 

changelog.d/15265.misc

@@ -0,0 +1 @@
+Add developer documentation for the Federation Sender and add a documentation mechanism using Sphinx.

dev-docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS ?=
+SPHINXBUILD ?= sphinx-build
+SOURCEDIR = .
+BUILDDIR = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+ @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+ @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

dev-docs/conf.py

@@ -0,0 +1,50 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "Synapse development"
+copyright = "2023, The Matrix.org Foundation C.I.C."
+author = "The Synapse Maintainers and Community"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+ "autodoc2",
+ "myst_parser",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for Autodoc2 ----------------------------------------------------
+
+autodoc2_docstring_parser_regexes = [
+ # this will render all docstrings as 'MyST' Markdown
+ (r".*", "myst"),
+]
+
+autodoc2_packages = [
+ {
+ "path": "../synapse",
+ # Don't render documentation for everything as a matter of course
+ "auto_mode": False,
+ },
+]
+
+
+# -- Options for MyST (Markdown) ---------------------------------------------
+
+# myst_heading_anchors = 2
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "furo"
+html_static_path = ["_static"]

dev-docs/index.rst

@@ -0,0 +1,22 @@
+.. Synapse Developer Documentation documentation master file, created by
+ sphinx-quickstart on Mon Mar 13 08:59:51 2023.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Welcome to the Synapse Developer Documentation!
+===========================================================
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Contents:
+
+ modules/federation_sender
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

dev-docs/modules/federation_sender.md

@@ -0,0 +1,5 @@
+Federation Sender
+=================
+
+```{autodoc2-docstring} synapse.federation.sender
+```