From d25e8a8ee8a693473912f4bb0e787a0426a44278 Mon Sep 17 00:00:00 2001 From: holger krekel Date: Wed, 26 Aug 2026 14:39:45 +0200 Subject: [PATCH] chore(doc): use sphinx roles for referencing repository files and dirs this allows PRs to add references without having to point to main where a file might not be, and thus fail CI. --- .github/workflows/docs-preview.yaml | 5 +++++ doc/source/conf.py | 16 ++++++++++++---- doc/source/faq.rst | 2 +- doc/source/overview.rst | 28 +++++++++++++--------------- 4 files changed, 31 insertions(+), 20 deletions(-) diff --git a/.github/workflows/docs-preview.yaml b/.github/workflows/docs-preview.yaml index ad320eac..529c1492 100644 --- a/.github/workflows/docs-preview.yaml +++ b/.github/workflows/docs-preview.yaml @@ -13,6 +13,11 @@ jobs: scripts: name: build runs-on: ubuntu-latest + env: + # Pin the repository links in the docs to this pull request's head commit + # so that linkcheck resolves files which only exist on the branch so far. + # see doc/conf.py + DOC_GITHUB_REF: ${{ github.event.pull_request.head.sha }} environment: name: 'staging.chatmail.at/doc/relay/' url: https://staging.chatmail.at/doc/relay/${{ steps.prepare.outputs.prid }} diff --git a/doc/source/conf.py b/doc/source/conf.py index 5523440d..9f254df1 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -3,6 +3,8 @@ # For the full list of built-in configuration values, see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html +import os + # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information @@ -16,18 +18,24 @@ author = 'chatmail collective' extensions = [ #'sphinx.ext.autodoc', #'sphinx.ext.viewdoc', + 'sphinx.ext.extlinks', 'sphinxcontrib.mermaid', ] templates_path = ['_templates'] exclude_patterns = [] -linkcheck_ignore = [ - # only resolves once the file is merged to main - r"https://github\.com/chatmail/relay/blob/main/chatmaild/src/chatmaild/defaults/appversions\.json", -] +# Repository links go through the roles below. +# CI sets DOC_GITHUB_REF to the head commit of a pull request, +gh_ref = os.environ.get("DOC_GITHUB_REF", "main") +extlinks = { + "repofile": (f"https://github.com/chatmail/relay/blob/{gh_ref}/%s", "%s"), + "repodir": (f"https://github.com/chatmail/relay/tree/{gh_ref}/%s", "%s"), +} +# Warn about repository links spelled out in full instead of using the roles. +extlinks_detect_hardcoded_links = True # -- Options for HTML output ------------------------------------------------- diff --git a/doc/source/faq.rst b/doc/source/faq.rst index a63baf15..2d7dc954 100644 --- a/doc/source/faq.rst +++ b/doc/source/faq.rst @@ -54,7 +54,7 @@ How can I upgrade my chatmail relay? ------------------------------------ To upgrade to the latest ``main`` branch, -``cd`` into your local checkout of `https://github.com/chatmail/relay/`_ +``cd`` into your local checkout of https://github.com/chatmail/relay/ and run the following commands: :: diff --git a/doc/source/overview.rst b/doc/source/overview.rst index 9c2dd4cf..6363a27a 100644 --- a/doc/source/overview.rst +++ b/doc/source/overview.rst @@ -6,13 +6,13 @@ Technical overview Directories of the relay repository ----------------------------------- -The `chatmail relay repository `_ +The `chatmail relay repository `_ has four main directories. ``scripts/`` ~~~~~~~~~~~~~ -`scripts `_ +:repodir:`scripts` offers two convenience tools for beginners: - ``initenv.sh`` installs a local virtualenv Python environment and @@ -71,7 +71,7 @@ The deployed system components of a chatmail relay are: ``chatmaild/`` ~~~~~~~~~~~~~~ -`chatmaild `_ +:repodir:`chatmaild` is a Python package containing several small services which handle authentication, trigger push notifications on new messages, ensure that outbound mails are encrypted, delete inactive users, and some @@ -83,25 +83,24 @@ that integrate with Dovecot and Postfix to achieve instant-onboarding and only relaying OpenPGP end-to-end messages encrypted messages. A short overview of ``chatmaild`` services: -- `doveauth `_ +- :repofile:`doveauth ` implements create-on-login address semantics and is used by Dovecot during IMAP login and by Postfix during SMTP/SUBMISSION login which in turn uses `Dovecot SASL `_ to authenticate logins. -- `chatmail-metadata `_ - is contacted by a `Dovecot lua - script `_ - to store user-specific relay-side config. On new messages, it `passes - the user’s push notification - token `_ +- :repofile:`chatmail-metadata ` + is contacted by a + :repofile:`Dovecot lua script ` + to store user-specific relay-side config. On new messages, it + :repofile:`passes the user’s push notification token ` to `notifications.delta.chat `_ so the push notifications on the user’s phone can be triggered by Apple/Google/Huawei. -- `chatmail-expire `_ +- :repofile:`chatmail-expire ` deletes old messages, large messages, and entire mailboxes of users who have not logged in for longer than ``delete_inactive_users_after`` days. @@ -109,15 +108,14 @@ short overview of ``chatmaild`` services: - ``chatmail-quota-expire`` is called by Dovecot's ``quota_warning`` mechanism and will automatically remove oldest messages to keep mailboxes well under ``max_mailbox_size``. -- `lastlogin `_ +- :repofile:`lastlogin ` is contacted by Dovecot when a user logs in and stores the date of the login. ``www/`` ~~~~~~~~~ -`www `_ contains -the html, css, and markdown files which make up a chatmail relay’s +:repodir:`www` contains the html, css, and markdown files which make up a chatmail relay’s web page. Edit them before deploying to make your chatmail relay stand out. @@ -253,7 +251,7 @@ App version information (experimental) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A chatmail relay ships the -`appversions.json `_ +:repofile:`appversions.json ` file of the ``chatmaild`` package and serves its content under the IMAP METADATA key ``/shared/vendor/deltachat/appversions``.