The new :cve: Sphinx role takes a CVE number as an argument and creates
a hyperlink to the relevant ISC Knowledgebase document that might have
more up-to-date or verbose information than the relevant release note.
This makes reaching ISC Knowledgebase pages directly from the release
notes easier.
Make all CVE references in the release notes use the new Sphinx role.
(cherry picked from commit 41b857e567)
RTD style default never wraps <th> and <td> elements and that just does
not work for real sentences or any other long lines.
We can reconsider styling some tables separately, but at the moment we
do not have use for tables with long but unwrappable lines so it's
easier to allow wrapping globally.
(cherry picked from commit a5dd98ac1b)
Older versions do not have "override" parameter in add_role_to_domain()
function signature. Luckily the override is _not_ required when
overidding the built-in standard domain roles for the first time, so we
just drop the paramter.
Tested with Sphinx 1.6.7 (does not have override) and Sphinx 4.5.0
(does have override).
Fixes: #3294
Related: !6086
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 7e7a946d44)
Converted using pandoc 2.14.2-14 on Arch Linux:
$ pandoc --shift-heading-level-by=-1 -f markdown -t rst README.md > doc/arm/build.rst
Plus hand-edit to remove sections other than Building BIND 9, remove
misindentation in section headers, and add a standard copyright header.
This commit converts the license handling to adhere to the REUSE
specification. It specifically:
1. Adds used licnses to LICENSES/ directory
2. Add "isc" template for adding the copyright boilerplate
3. Changes all source files to include copyright and SPDX license
header, this includes all the C sources, documentation, zone files,
configuration files. There are notes in the doc/dev/copyrights file
on how to add correct headers to the new files.
4. Handle the rest that can't be modified via .reuse/dep5 file. The
binary (or otherwise unmodifiable) files could have license places
next to them in <foo>.license file, but this would lead to cluttered
repository and most of the files handled in the .reuse/dep5 file are
system test files.
(cherry picked from commit 58bd26b6cf)
Some Sphinx variables used in the ARM are only set in
doc/arm/Makefile.in. This works fine when building the ARM using
"make", but does not work with Read the Docs, which only looks at
conf.py files.
Since Read the Docs does not run ./configure, renaming conf.py to
conf.py.in and using Autoconf output variables is not a feasible
solution.
Instead, extend doc/arm/conf.py with some Python code which processes
the "version" file using regular expressions and sets the relevant
Sphinx variables accordingly. As this solution also works fine when
building the ARM using "make", drop the relevant -D options from the
list of sphinx-build options used for building the ARM in
doc/arm/Makefile.in.
Note that the man_SPHINXOPTS counterparts of the removed -D switches are
left intact because doc/man/conf.py is a separate Sphinx project which
is only processed using "make" and duplicating the Python code added to
doc/arm/conf.py by this commit would be inelegant.
(cherry picked from commit 38d251e11b)
The ReferenceRole class is only available in Sphinx >= 2.0.0, which
makes building BIND 9 documentation impossible with older Sphinx
versions:
Running Sphinx v1.7.6
Configuration error:
There is a programable error in your configuration file:
Traceback (most recent call last):
File "/usr/lib/python3.6/site-packages/sphinx/config.py", line 161, in __init__
execfile_(filename, config)
File "/usr/lib/python3.6/site-packages/sphinx/util/pycompat.py", line 150, in execfile_
exec_(code, _globals)
File "conf.py", line 21, in <module>
from sphinx.util.docutils import ReferenceRole
ImportError: cannot import name 'ReferenceRole'
Work around the problem by defining a stub version of the ReferenceRole
class if the latter cannot be imported. This allows documentation
(without GitLab hyperlinks in release notes) to be built with older
Sphinx versions.
(cherry picked from commit 8f8bbae3fc)
Address the following warnings reported by PyLint 2.10.2:
************* Module conf
doc/arm/conf.py:90:10: W1406: The u prefix for strings is no longer necessary in Python >=3.0 (redundant-u-string-prefix)
doc/arm/conf.py:92:12: W1406: The u prefix for strings is no longer necessary in Python >=3.0 (redundant-u-string-prefix)
doc/arm/conf.py:93:9: W1406: The u prefix for strings is no longer necessary in Python >=3.0 (redundant-u-string-prefix)
doc/arm/conf.py:139:31: W1406: The u prefix for strings is no longer necessary in Python >=3.0 (redundant-u-string-prefix)
doc/man/conf.py:33:10: W1406: The u prefix for strings is no longer necessary in Python >=3.0 (redundant-u-string-prefix)
doc/man/conf.py:38:12: W1406: The u prefix for strings is no longer necessary in Python >=3.0 (redundant-u-string-prefix)
doc/man/conf.py:39:9: W1406: The u prefix for strings is no longer necessary in Python >=3.0 (redundant-u-string-prefix)
(cherry picked from commit e5944bc610)
Define a :gl: Sphinx role that takes a GitLab issue/MR number as an
argument and creates a hyperlink to the relevant ISC GitLab URL. This
makes it easy to reach ISC GitLab pages directly from the release notes.
Make all GitLab references in the release notes use the new Sphinx role.
(cherry picked from commit 2fadf29e6b)
The release notes were previously built as a separate document
(including the PDF version). It was agreed that this doesn't make much
sense, so the release notes are now included only as an appendix to the
BIND 9 ARM.
(cherry picked from commit 8eb2323ec3)
The ARM and the manpages have been converted into Sphinx documentation
format.
Sphinx uses reStructuredText as its markup language, and many of its
strengths come from the power and straightforwardness of
reStructuredText and its parsing and translating suite, the Docutils.
(cherry picked from commit 9fb6d11abb)
