From 1322372a0c9b6efd3af866455bbdb25e6d55c650 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Wed, 16 Mar 2022 10:49:17 +0100 Subject: [PATCH] Restructure includes for ARM chapters 1 (Intro) and 2 (Requirements) We have had perpetual problem with Sphinx implicitly double-including files. To avoid that problem all files with name suffix .inc.rst are now ignored by Sphinx, and writter can conveniently include them without modifying conf.py for each and every file. --- doc/arm/Makefile.am | 31 ++++++++++--------- doc/arm/advanced.rst | 12 +++---- doc/arm/{build.rst => build.inc.rst} | 0 doc/arm/{catz.rst => catz.inc.rst} | 0 doc/arm/chapter1.rst | 12 +++++++ doc/arm/chapter2.rst | 14 +++++++++ doc/arm/conf.py | 13 +------- doc/arm/configuration.rst | 2 +- doc/arm/{dlz.rst => dlz.inc.rst} | 0 doc/arm/{dnssec.rst => dnssec.inc.rst} | 0 doc/arm/{dyndb.rst => dyndb.inc.rst} | 0 doc/arm/index.rst | 4 +-- ...{introduction.rst => introduction.inc.rst} | 0 ...egories.rst => logging-categories.inc.rst} | 0 ...{managed-keys.rst => managed-keys.inc.rst} | 0 doc/arm/{pkcs11.rst => pkcs11.inc.rst} | 0 doc/arm/{platforms.rst => platforms.inc.rst} | 0 doc/arm/{plugins.rst => plugins.inc.rst} | 0 doc/arm/reference.rst | 2 +- ...{requirements.rst => requirements.inc.rst} | 2 -- util/check-categories.sh | 2 +- 21 files changed, 55 insertions(+), 39 deletions(-) rename doc/arm/{build.rst => build.inc.rst} (100%) rename doc/arm/{catz.rst => catz.inc.rst} (100%) create mode 100644 doc/arm/chapter1.rst create mode 100644 doc/arm/chapter2.rst rename doc/arm/{dlz.rst => dlz.inc.rst} (100%) rename doc/arm/{dnssec.rst => dnssec.inc.rst} (100%) rename doc/arm/{dyndb.rst => dyndb.inc.rst} (100%) rename doc/arm/{introduction.rst => introduction.inc.rst} (100%) rename doc/arm/{logging-categories.rst => logging-categories.inc.rst} (100%) rename doc/arm/{managed-keys.rst => managed-keys.inc.rst} (100%) rename doc/arm/{pkcs11.rst => pkcs11.inc.rst} (100%) rename doc/arm/{platforms.rst => platforms.inc.rst} (100%) rename doc/arm/{plugins.rst => plugins.inc.rst} (100%) rename doc/arm/{requirements.rst => requirements.inc.rst} (98%) diff --git a/doc/arm/Makefile.am b/doc/arm/Makefile.am index 9db674b8d6..bfc12db128 100644 --- a/doc/arm/Makefile.am +++ b/doc/arm/Makefile.am @@ -2,29 +2,32 @@ include $(top_srcdir)/Makefile.top include $(top_srcdir)/Makefile.docs EXTRA_DIST = \ - conf.py \ - isc-logo.pdf \ advanced.rst \ - build.rst \ - catz.rst \ + build.inc.rst \ + catz.inc.rst \ + chapter1.rst \ + chapter2.rst \ configuration.rst \ - dlz.rst \ + conf.py \ + dlz.inc.rst \ dnssec-guide.rst \ - dnssec.rst \ - dyndb.rst \ + dnssec.inc.rst \ + dyndb.inc.rst \ general.rst \ history.rst \ index.rst \ - introduction.rst \ - logging-categories.rst \ - managed-keys.rst \ + introduction.inc.rst \ + isc-logo.pdf \ + logging-categories.inc.rst \ + managed-keys.inc.rst \ manpages.rst \ notes.rst \ - pkcs11.rst \ - platforms.rst \ - plugins.rst \ + pkcs11.inc.rst \ + platforms.inc.rst \ + plugins.inc.rst \ reference.rst \ - requirements.rst \ + requirements.inc.rst \ + requirements.txt \ security.rst \ troubleshooting.rst \ ../dnssec-guide \ diff --git a/doc/arm/advanced.rst b/doc/arm/advanced.rst index 30fdcdb7b7..10457c87fd 100644 --- a/doc/arm/advanced.rst +++ b/doc/arm/advanced.rst @@ -779,12 +779,12 @@ according to its parent, should have been secure. response; parent indicates it should be secure." -.. include:: dnssec.rst -.. include:: managed-keys.rst -.. include:: pkcs11.rst -.. include:: dlz.rst -.. include:: dyndb.rst -.. include:: catz.rst +.. include:: dnssec.inc.rst +.. include:: managed-keys.inc.rst +.. include:: pkcs11.inc.rst +.. include:: dlz.inc.rst +.. include:: dyndb.inc.rst +.. include:: catz.inc.rst .. _ipv6: diff --git a/doc/arm/build.rst b/doc/arm/build.inc.rst similarity index 100% rename from doc/arm/build.rst rename to doc/arm/build.inc.rst diff --git a/doc/arm/catz.rst b/doc/arm/catz.inc.rst similarity index 100% rename from doc/arm/catz.rst rename to doc/arm/catz.inc.rst diff --git a/doc/arm/chapter1.rst b/doc/arm/chapter1.rst new file mode 100644 index 0000000000..a392637fdf --- /dev/null +++ b/doc/arm/chapter1.rst @@ -0,0 +1,12 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +.. include:: introduction.inc.rst diff --git a/doc/arm/chapter2.rst b/doc/arm/chapter2.rst new file mode 100644 index 0000000000..2e50f15b75 --- /dev/null +++ b/doc/arm/chapter2.rst @@ -0,0 +1,14 @@ +.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") +.. +.. SPDX-License-Identifier: MPL-2.0 +.. +.. This Source Code Form is subject to the terms of the Mozilla Public +.. License, v. 2.0. If a copy of the MPL was not distributed with this +.. file, you can obtain one at https://mozilla.org/MPL/2.0/. +.. +.. See the COPYRIGHT file distributed with this work for additional +.. information regarding copyright ownership. + +.. include:: requirements.inc.rst +.. include:: platforms.inc.rst +.. include:: build.inc.rst diff --git a/doc/arm/conf.py b/doc/arm/conf.py index 742626335b..60131b41f6 100644 --- a/doc/arm/conf.py +++ b/doc/arm/conf.py @@ -142,18 +142,7 @@ exclude_patterns = [ '_build', 'Thumbs.db', '.DS_Store', - '*.grammar.rst', - '*.zoneopts.rst', - 'build.rst', - 'catz.rst', - 'dlz.rst', - 'dnssec.rst', - 'dyndb.rst', - 'logging-categories.rst', - 'managed-keys.rst', - 'pkcs11.rst', - 'platforms.rst', - 'plugins.rst' + '*.inc.rst' ] # The master toctree document. diff --git a/doc/arm/configuration.rst b/doc/arm/configuration.rst index 6ef62e2b38..807891c5a3 100644 --- a/doc/arm/configuration.rst +++ b/doc/arm/configuration.rst @@ -312,4 +312,4 @@ described in the following table. These signals can be sent using the | ``SIGINT`` | Causes the server to clean up and exit. | +--------------+-------------------------------------------------------------+ -.. include:: plugins.rst +.. include:: plugins.inc.rst diff --git a/doc/arm/dlz.rst b/doc/arm/dlz.inc.rst similarity index 100% rename from doc/arm/dlz.rst rename to doc/arm/dlz.inc.rst diff --git a/doc/arm/dnssec.rst b/doc/arm/dnssec.inc.rst similarity index 100% rename from doc/arm/dnssec.rst rename to doc/arm/dnssec.inc.rst diff --git a/doc/arm/dyndb.rst b/doc/arm/dyndb.inc.rst similarity index 100% rename from doc/arm/dyndb.rst rename to doc/arm/dyndb.inc.rst diff --git a/doc/arm/index.rst b/doc/arm/index.rst index 431f0cd598..7dec5cf947 100644 --- a/doc/arm/index.rst +++ b/doc/arm/index.rst @@ -17,8 +17,8 @@ BIND 9 Administrator Reference Manual :numbered: :maxdepth: 2 - introduction - requirements + chapter1 + chapter2 configuration reference advanced diff --git a/doc/arm/introduction.rst b/doc/arm/introduction.inc.rst similarity index 100% rename from doc/arm/introduction.rst rename to doc/arm/introduction.inc.rst diff --git a/doc/arm/logging-categories.rst b/doc/arm/logging-categories.inc.rst similarity index 100% rename from doc/arm/logging-categories.rst rename to doc/arm/logging-categories.inc.rst diff --git a/doc/arm/managed-keys.rst b/doc/arm/managed-keys.inc.rst similarity index 100% rename from doc/arm/managed-keys.rst rename to doc/arm/managed-keys.inc.rst diff --git a/doc/arm/pkcs11.rst b/doc/arm/pkcs11.inc.rst similarity index 100% rename from doc/arm/pkcs11.rst rename to doc/arm/pkcs11.inc.rst diff --git a/doc/arm/platforms.rst b/doc/arm/platforms.inc.rst similarity index 100% rename from doc/arm/platforms.rst rename to doc/arm/platforms.inc.rst diff --git a/doc/arm/plugins.rst b/doc/arm/plugins.inc.rst similarity index 100% rename from doc/arm/plugins.rst rename to doc/arm/plugins.inc.rst diff --git a/doc/arm/reference.rst b/doc/arm/reference.rst index 0201046254..eba8148369 100644 --- a/doc/arm/reference.rst +++ b/doc/arm/reference.rst @@ -760,7 +760,7 @@ The following are the available categories and brief descriptions of the types of log information they contain. More categories may be added in future BIND releases. -.. include:: logging-categories.rst +.. include:: logging-categories.inc.rst .. _query_errors: diff --git a/doc/arm/requirements.rst b/doc/arm/requirements.inc.rst similarity index 98% rename from doc/arm/requirements.rst rename to doc/arm/requirements.inc.rst index 09f0f427ef..90bd0e965a 100644 --- a/doc/arm/requirements.rst +++ b/doc/arm/requirements.inc.rst @@ -70,5 +70,3 @@ much memory or CPU power as in the first alternative, but this has the disadvantage of making many more external queries, as none of the name servers share their cached data. -.. include:: platforms.rst -.. include:: build.rst diff --git a/util/check-categories.sh b/util/check-categories.sh index 6a4b0232da..c8c6e3cc2c 100644 --- a/util/check-categories.sh +++ b/util/check-categories.sh @@ -19,7 +19,7 @@ list1=$( sort -u ) list2=$( - sed -ne 's/^``\(.*\)``/\1/p' doc/arm/logging-categories.rst | + sed -ne 's/^``\(.*\)``/\1/p' doc/arm/logging-categories.inc.rst | sort -u ) status=0