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.

diff --git a/doc/arm/Makefile.am b/doc/arm/Makefile.am
index 9db674b8d65abf74e80c12d539f69b22d0464c0c..bfc12db128ff0ba3fb66a58904812d65c7a58be2 100644 (file)
--- 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 30fdcdb7b776a53ee51706461afa3eb6e69a4c04..10457c87fd7f577e0e17d11fc9a2893f875b5530 100644 (file)
--- 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 (file)
index 0000000..a392637
--- /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 (file)
index 0000000..2e50f15
--- /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 742626335b5091ad17aeb5f7b92588df31394bbe..60131b41f6e2f4ebbcdca32824596298a4657260 100644 (file)
--- 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 6ef62e2b383d6d17e53d79231b6785fce0e0fc46..807891c5a31abbc6af95bafc8bc079f344ff1184 100644 (file)
--- 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 431f0cd598bf5f74f21d695eb0abfb8b82a8302a..7dec5cf9474074a60ac4df80289d7e9182d73de9 100644 (file)
--- 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 020104625463f943aacd11933b673b71c30f3453..eba81483691437a09434c8c8c10a74c2ee3e1d0a 100644 (file)
--- 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 09f0f427ef970204fc1ff437e3e2524221246930..90bd0e965a02916122a7370bd2bf79abf8bafdf1 100644 (file)
--- 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 6a4b0232da6cf8237f489b1760c0c3299e14d221..c8c6e3cc2cd0e2408a45070d7db9cda3dcaaff27 100644 (file)
--- 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