From mboxrd@z Thu Jan 1 00:00:00 1970 Delivery-date: Tue, 13 Dec 2022 14:24:39 +0100 Received: from metis.ext.pengutronix.de ([2001:67c:670:201:290:27ff:fe1d:cc33]) by lore.white.stw.pengutronix.de with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.94.2) (envelope-from ) id 1p55Gw-002f7i-D8 for lore@lore.pengutronix.de; Tue, 13 Dec 2022 14:24:38 +0100 Received: from localhost ([127.0.0.1] helo=metis.ext.pengutronix.de) by metis.ext.pengutronix.de with esmtp (Exim 4.92) (envelope-from ) id 1p55Gv-0002xD-KU; Tue, 13 Dec 2022 14:24:37 +0100 Received: from drehscheibe.grey.stw.pengutronix.de ([2a0a:edc0:0:c01:1d::a2]) by metis.ext.pengutronix.de with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1p55GC-0002wz-U3; Tue, 13 Dec 2022 14:23:52 +0100 Received: from [2a0a:edc0:0:1101:1d::ac] (helo=dude04.red.stw.pengutronix.de) by drehscheibe.grey.stw.pengutronix.de with esmtp (Exim 4.94.2) (envelope-from ) id 1p55GB-004G4i-HJ; Tue, 13 Dec 2022 14:23:52 +0100 Received: from rhi by dude04.red.stw.pengutronix.de with local (Exim 4.94.2) (envelope-from ) id 1p55GB-00CxrK-8n; Tue, 13 Dec 2022 14:23:51 +0100 From: Roland Hieber To: ptxdist@pengutronix.de Date: Tue, 13 Dec 2022 14:23:49 +0100 Message-Id: <20221213132349.3082538-1-rhi@pengutronix.de> X-Mailer: git-send-email 2.30.2 MIME-Version: 1.0 Mail-Followup-To: Roland Hieber , ptxdist@pengutronix.de Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Subject: [ptxdist] [PATCH] doc: include instructions for layered documentation X-BeenThere: ptxdist@pengutronix.de X-Mailman-Version: 2.1.29 Precedence: list List-Id: PTXdist Development Mailing List List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: ptxdist@pengutronix.de Cc: Roland Hieber Sender: "ptxdist" X-SA-Exim-Connect-IP: 127.0.0.1 X-SA-Exim-Mail-From: ptxdist-bounces@pengutronix.de X-SA-Exim-Scanned: No (on metis.ext.pengutronix.de); SAEximRunCond expanded to false Signed-off-by: Roland Hieber --- doc/including_bsp_doc.inc | 34 ++++++++++++++++++++++++++++++++++ doc/index-layer-0-ptxdist.rst | 1 + doc/index.rst | 2 +- 3 files changed, 36 insertions(+), 1 deletion(-) create mode 100644 doc/index-layer-0-ptxdist.rst diff --git a/doc/including_bsp_doc.inc b/doc/including_bsp_doc.inc index 775ad33975ae..ca6f7519e407 100644 --- a/doc/including_bsp_doc.inc +++ b/doc/including_bsp_doc.inc @@ -103,3 +103,37 @@ external dependencies. Refer the PTXdist file ``doc/conf.py`` for more information on variable substitution. This PTXdist global file can be superseded by a local copy as well. + +Documentation structure for layered BSPs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When you call ``ptxdist docs-html`` in a layer, PTXdist will assemble the +``doc/`` directory from all lower layers in the usual layering fashion, +and flatten it into a single directory. +In the highest-level table of contents, PTXdist uses a wildcard match for +``index-layer*`` files, which is the entry point to integrate documentation for +your own layers by creating files with that pattern. +It is advisable to number the index files accordingly so their ordering in the +documentation reflects the layer order. +PTXdist itself uses the file ``index-layer-0-ptxdist.rst`` to include the title +page of the PTXdist manual first, and includes the rest of the PTXdist +documentation after the layer-specific files. + +For example, see the following directory structure:: + + my-bsp/ + ├── common/ + │   └── doc/ + │ └── index-layer-1-common.rst + └── product-layer + . ├── base/ -> ../common + .   └── doc + . └── index-layer-2-product.rst + +In this example, the contents of ``index-layer-1-common.rst`` and +``index-layer-2-product.rst`` would describe some layer-specific content, or +even have their own table of contents in the usual reStructuredTest fashion to +include more sub-sections in separate files. +The documentation built for the *product-layer* will therefore include a +section each for the *common* layer documentation, then for the *product-layer* +documentation, and finally the rest of the PTXdist documentation. diff --git a/doc/index-layer-0-ptxdist.rst b/doc/index-layer-0-ptxdist.rst new file mode 100644 index 000000000000..4576503a3661 --- /dev/null +++ b/doc/index-layer-0-ptxdist.rst @@ -0,0 +1 @@ +.. include:: welcome.rst diff --git a/doc/index.rst b/doc/index.rst index 6a01d6dd7bb8..29c0dc9dea9a 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -11,7 +11,7 @@ Welcome to the PTXdist Universe :numbered: 2 :maxdepth: 3 - welcome + index-layer* environment user_manual_section dev_manual -- 2.30.2