]> git.ipfire.org Git - thirdparty/bind9.git/commit
Use unique program + option names for link anchors to support Sphinx 1.8.5
authorPetr Špaček <pspacek@isc.org>
Mon, 25 Apr 2022 10:07:24 +0000 (12:07 +0200)
committerPetr Špaček <pspacek@isc.org>
Mon, 25 Apr 2022 12:27:34 +0000 (14:27 +0200)
commitbbb24264bbc88285d127ebc948b888786c03be82
tree6cdf74b52382ce67dcbcba938c7e4cf8fcb4b0aa
parent870f785e4948ec85c150aaefd51dde0e993d89a5
Use unique program + option names for link anchors to support Sphinx 1.8.5

Sphinx "standard domain" provides directive types ".. program::" and
".. option::" to create link anchor for a program name + option combination.
These can be referenced using :ref:`program option` syntax.

The problem is that Sphinx 1.8.5 (e.g. in Ubuntu 18.04) generates
conflicting link targets if a page contains two option directives
starting with the same word, e.g.:

.. program:: dnssec-settime
.. option:: -P date
.. option:: -P ds date

The reason is that option directive consumes only first word as "option
name" (-P) and all the rest is considered "option argument" (date, ds
date). Newer versions of Sphinx (e.g. 4.5.0) handle this by creating
numbered link anchors, but older versions warn and BIND build system
turns the warning into a hard error.

To handle that we use method recommended by Sphinx maintainer:
https://github.com/sphinx-doc/sphinx/issues/10218#issuecomment-1059925508
As a bonus it provides more accurate link anchors for sub-options.

Alternatives considered:
- Replacing standard domain definition of .. option - causes more
  problems, see BIND issue #3294.
- Removing hyperlinks for options - that would be a step back.

Fixes: #3295
bin/dnssec/dnssec-importkey.rst
bin/dnssec/dnssec-keyfromlabel.rst
bin/dnssec/dnssec-keygen.rst
bin/dnssec/dnssec-settime.rst
bin/rndc/rndc.rst
doc/man/dnssec-importkey.1in
doc/man/dnssec-keyfromlabel.1in
doc/man/dnssec-keygen.1in
doc/man/dnssec-settime.1in
doc/man/rndc.8in