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.

(cherry-picked from commit 7e7a946d4446e6a91fb994a8c2456289e8bf6e42)

diff --git a/doc/arm/conf.py b/doc/arm/conf.py
index 19ac91b7fa1a3fc7a17f25368c899c3591474f4c..b147521a9e7d271ad7b88b99f371cb651cca694a 100644 (file)
--- a/doc/arm/conf.py
+++ b/doc/arm/conf.py
@@ -79,8 +79,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.

diff --git a/doc/man/conf.py b/doc/man/conf.py
index edce4c28a01599c8a457b3f4aa473a0ae48bd7ca..b3814848cc488e3b366bfd7bac01034b7499b92d 100644 (file)
--- a/doc/man/conf.py
+++ b/doc/man/conf.py
@@ -106,3 +106,6 @@ man_pages = [
     ('rndc', 'rndc', 'name server control utility', author, 8),
     ('tsig-keygen', 'tsig-keygen', 'TSIG key generation tool', author, 8),
     ]
+
+def setup(app):
+    app.add_crossref_type('iscman', 'iscman', 'pair: %s; manual page')