2
0
mirror of https://gitlab.isc.org/isc-projects/bind9 synced 2025-08-31 14:35:26 +00:00

Introduce new Sphinx role iscman for ISC manual pages

The new directive and role "iscman" allow to tag & reference man pages in
our source tree. Essentially it is just namespacing for ISC man pages,
but it comes with couple benefits.

Differences from .. _man_program label we formerly used:
- Does not expand :ref:`man_program` into full text of the page header.
- Generates index entry with category "manual page".
- Rendering style is closer to ubiquitous to the one produced
  by ``named`` syntax.

Differences from Sphinx built-in :manpage: role:
- Supports all builders with support for cross-references.
- Generates internal links (unlike :manpage: which generates external
  URLs).
- Checks that target exists withing our source tree.
This commit is contained in:
Petr Špaček
2022-03-03 15:32:35 +01:00
parent ccc6378355
commit 7e7a946d44
35 changed files with 39 additions and 1 deletions

View File

@@ -81,8 +81,9 @@ class GitLabRefRole(ReferenceRole):
raise ValueError
def setup(_):
def setup(app):
roles.register_local_role('gl', GitLabRefRole(GITLAB_BASE_URL))
app.add_crossref_type('iscman', 'iscman', 'pair: %s; manual page')
#
# Configuration file for the Sphinx documentation builder.