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

@@ -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 }}

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 -------------------------------------------------

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:
 
    ::

doc/source/overview.rst

@@ -6,13 +6,13 @@ Technical overview
 Directories of the relay repository
 -----------------------------------
 
-The `chatmail relay repository <https://github.com/chatmail/relay/tree/main/>`_
+The `chatmail relay repository <https://github.com/chatmail/relay>`_
 has four main directories.
 
 ``scripts/``
 ~~~~~~~~~~~~~
 
-`scripts <https://github.com/chatmail/relay/tree/main/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 <https://github.com/chatmail/relay/tree/main/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 <https://github.com/chatmail/relay/blob/main/chatmaild/src/chatmaild/doveauth.py>`_
+-  :repofile:`doveauth <chatmaild/src/chatmaild/doveauth.py>`
    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
    <https://doc.dovecot.org/2.3/configuration_manual/authentication/dict/#complete-example-for-authenticating-via-a-unix-socket>`_
    to authenticate logins.
 
--  `chatmail-metadata <https://github.com/chatmail/relay/blob/main/chatmaild/src/chatmaild/metadata.py>`_
-   is contacted by a `Dovecot lua
-   script <https://github.com/chatmail/relay/blob/main/cmdeploy/src/cmdeploy/dovecot/push_notification.lua>`_
-   to store user-specific relay-side config. On new messages, it `passes
-   the user’s push notification
-   token <https://github.com/chatmail/relay/blob/main/chatmaild/src/chatmaild/notifier.py>`_
+-  :repofile:`chatmail-metadata <chatmaild/src/chatmaild/metadata.py>`
+   is contacted by a
+   :repofile:`Dovecot lua script <cmdeploy/src/cmdeploy/dovecot/push_notification.lua>`
+   to store user-specific relay-side config. On new messages, it
+   :repofile:`passes the user’s push notification token <chatmaild/src/chatmaild/notifier.py>`
    to
    `notifications.delta.chat <https://delta.chat/en/help#instant-delivery>`_
    so the push notifications on the user’s phone can be triggered by
    Apple/Google/Huawei.
 
--  `chatmail-expire <https://github.com/chatmail/relay/blob/main/chatmaild/src/chatmaild/expire.py>`_
+-  :repofile:`chatmail-expire <chatmaild/src/chatmaild/expire.py>`
    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 <https://github.com/chatmail/relay/blob/main/chatmaild/src/chatmaild/lastlogin.py>`_
+-  :repofile:`lastlogin <chatmaild/src/chatmaild/lastlogin.py>`
    is contacted by Dovecot when a user logs in and stores the date of
    the login.
 
 ``www/``
 ~~~~~~~~~
 
-`www <https://github.com/chatmail/relay/tree/main/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 <https://github.com/chatmail/relay/blob/main/chatmaild/src/chatmaild/defaults/appversions.json>`_
+:repofile:`appversions.json <chatmaild/src/chatmaild/defaults/appversions.json>`
 file of the ``chatmaild`` package
 and serves its content under the IMAP METADATA key
 ``/shared/vendor/deltachat/appversions``.