Documentation: GitHub Links#

The GitHub link shorthand allows compact Markdown links such as [#42](gh), [v1.2.3](gh), or [src/appxc](gh). During the documentation build, these links resolve to full GitHub URLs.

Situation#

Documentation often references source files, issues, and versions but accessing the details of those references would require an actual link to the referenced source. Some examples:

Development documentation is kept concise, with more detail added to source files. The same can apply to user-facing module documentation which will not repeat docstring details.
Issue numbers and versions are often referenced for open topics while new features are being developed.

Another common situation affecting doucumented source code references is refactoring. When file names or paths change, links in the documentation can become invalid without being noticed and then cause confusion.

Status Quo#

Built-in Markdown links would require something like [#42](<project URL>/issues/42). Even this is a short example, and <project URL> shortens it further. In Markdown files, these links are verbose and require redundant information because the link text is repeated in the URL. As a result, references may still be mentioned, but the link itself is often omitted, creating a barrier to the additional information.

Approach#

A Sphinx extension, doc/_ext/github_links.py , supports links to:

the project via [APPXC](gh), resulting in APPXC
issues or PRs via [#61](gh), resulting in #61
source folders via [doc/dev](gh), resulting in doc/dev
source files via [doc/dev/concepts/doc-github-links.md](gh), resulting in doc/dev/concepts/doc-github-links.md
versions, either explicitly via [v0.0.2](gh), resulting in v0.0.2 or the current version via [gh:version](gh), resulting in gh:version

The syntax also supports the following alternatives:

explicit targets with arbitrary link text via [workflow](gh:.github/workflows/cd.yml), resulting in workflow
a file name as the link text while providing only the path as additional information, such as [doc-github-links.md](gh:path:doc/dev/concepts), resulting in doc-github-links.md

The extension uses the release variable in conf.py and links to files and paths for the version that matches the documentation build. Development builds and local builds that do not have a tagged release use the current checkout commit ID.

File and Path Checks#

Links to files and paths are verified against the file system. If a file or path does not exist, the build raises an error. This helps ensure that the documentation links only to files and paths that actually exist, provided this extension is used.

Additional Considerations#

Alternative Hooks#

The link syntax []() was selected as a hook because it is the default for links and supports natural reading of the markdown source. You read the text in [] and jump over the implementation detail in ().
- There are probably many alternatives but a role may be a very common approach to add behavior. A role based syntax, however, would make you read some implementation detail first before the actual text is found and :gh:#15 is hard to read.
There were many experiments before ending up with just (gh). (@gh) provided more awareness on the special handling