From now on all per-version notes link to the global list
of Known Issues. If there is a new note it should be listed twice:
In the per-version list, and in the global list.
(cherry picked from commit c58dd2790a)
Make the Sphinx version listed in doc/arm/requirements.txt match the
version currently used in GitLab CI, so that Read the Docs builds the
documentation using the same Python software versions as those used in
GitLab CI.
(cherry picked from commit a8f0ab7df6)
For the prefetch "trigger" parameter ARM states that when a cache
record with a lower TTL value is encountered during query processing,
it is refreshed. But in reality, the record is refreshed when the TTL
value is lower or equal to the configured "trigger" value.
Fix the documentation to make it match with with the code.
(cherry picked from commit ef344b1f52)
Add 'inline-signing yes;' to configuration examples to have working
copy paste configurations.
(cherry picked from commit b13a0c8836d2d8bc5b4de1cdfcdb2057c0bb9d93)
This change was made in !6403, but the appropriate documentation
changes were not applied to the ARM.
(cherry picked from commit 7231383e4cc57caac36d03055e8627b12aa4b91a)
Make documentation building successful even on RHEL9 sphinx 3.4.3. It
does not like case-insensitive matching of terms, so provide lowercase
text description with Uppercase word reference.
(cherry picked from commit bc6c6b1184)
Add more text about the importance of properly securing the statistics
channel and what is and what is not considered a security vulnerability.
(cherry-picked from commit 6869c98d36)
The "max-zone-ttl" option should now be configured as part of
dnssec-policy. Use of this option in zone/view/options will be ignored
in any zone that also has dnssec-policy configured.
Mostly deduplicating and linking information across the ARM.
Generally people should not touch it unless they what they are doing, so
let's try to discourage them a bit.
(cherry picked from commit bffa3063f0)
This is essentially a backport of !6296.
Replace DNSSEC chapter with version from the main branch, commit
901b6425d2.
There were structural changes to the ARM in the main branch, and
replacing the whole file with a new version is an order of magniture
easier than attempting to cherry-pick individual changes which should, in
the end, produce the same file under a different name.
File names in the main branch and v9_16 are now in sync (for the DNSSEC
chapter).
Fixes: #3320
Make clear that inline-signing stores DNSSEC records in a signed
version of the zone, using the zone's filename plus ".signed" extension.
Tell that dynamic zones store updates in the zone's filename.
DNSSEC records for dynamic zones also go in the zone's filename, unless
inline-signing is enabled.
Then, dnssec-policy assumes inline-signing, but only if the zone is
not dynamic.
(cherry picked from commit 8860f6b4ff)
After enormous amount of bikesheding about colors we decided to override
ReadTheDocs default style for literals (``literal`` in the RST markup).
Justification:
- The default RTD "light red literal on white background" is hard to
read. https://webaim.org/resources/contrastchecker/ reports that text
colored as rgb(231, 76, 60) on white background has insufficient
contrast.
- The ARM has enormous amount of literals all over the place and thus
one sentence can contain several black/red/black color changes. This
is distracting. As a consequence, the ARM looks like a Geronimo
Stilton book.
What we experimented with as replacements for red:
- Green - way too distracting
- Blue - too similar to "usual clickable link"
- Violet - too Geronimo Stilton style
- Brown - better but still distracting
After all the bikesheding we settled on black, i.e. the same as all
"normal" text. I.e. the color is now the same and literals are denoted
by monospaced font and a box around the literal. This has best contrast
and is way less distracting than it used to be.
This lead to a new problem: Internal references to "term definitions"
defined using directives like .. option:: were rendered almost the same
as literals:
- References: monospaced + box + bold + clickable
- Literals: monospaced + box To distinguish these two we added black
dotted underline to clickable references.
I hereby declare the bikeshed painted.
(cherry picked from commit 833af31e7b)
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)
Remove the line "This address must appear in the secondary server’s
parental-agents zone clause". This line is a copy paste error from
notify-source.
Rewrap.
(cherry picked from commit 313f606692)
This seems to be most appropriate way to ensure consistency between
release tarballs and public presentation on ReadTheDocs.
Previous attempt with removing docutils constraint, which relied on pip
depedency solver to pick the same packages as in CI was flawed. RTD
installs a bit different set of packages so it was inherently
unreliable.
As a result RTD pulled in sphinx-rtd-theme==0.4.3 while CI
had 1.0.0, and this inconsistency caused Table of Contents in Release
Notes to render incorrectly. Previous solution was to downgrade
docutils to < 0.17, but I think we should rather pin exact versions.
For the long history of messing with versions read also
isc-projects/bind9@2a8eda0084isc-projects/images@d4435b97beisc-projects/bind9@6a2daddf5b
(cherry picked from commit 6088ba3837)
Currently our CI images we use to build docs (which subsequently get
into release tarballs) are using docutils 0.17.1, which is latest version
which fulfills Sphinx 4.5.0 requirement for docutils < 0.18.
The old requirement for docutils < 0.17 was causing discrepancy between
the way we build release artifacts and the docs on ReadTheDocs.org which
uses doc/arm/requirements.txt from our repo.
Remove the limit for RDT with hope that it will pull latest permissible
version of docutils.
For the long history of messing with docutils version read also
isc-projects/images@d4435b97beisc-projects/bind9@6a2daddf5b
(cherry picked from commit 2a8eda0084)
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
Matthijs Mekking
Michal Nowak
Petr Špaček
Michał Kępień
Aram Sargsyan
Petr MenšíkandPetr Špaček
Ondřej SurýandPetr Špaček
Evan Hunt
Tom Krizek