From mboxrd@z Thu Jan 1 00:00:00 1970 Delivery-date: Tue, 03 Jan 2023 12:09:17 +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 1pCfAU-000MHr-Ig for lore@lore.pengutronix.de; Tue, 03 Jan 2023 12:09:17 +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 1pCfAT-0004oT-4Y; Tue, 03 Jan 2023 12:09:17 +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 1pCf9k-0002S2-HJ; Tue, 03 Jan 2023 12:08:32 +0100 Received: from [2a0a:edc0:0:1101:1d::54] (helo=dude05.red.stw.pengutronix.de) by drehscheibe.grey.stw.pengutronix.de with esmtp (Exim 4.94.2) (envelope-from ) id 1pCf9j-003YB0-Tp; Tue, 03 Jan 2023 12:08:31 +0100 Received: from mol by dude05.red.stw.pengutronix.de with local (Exim 4.94.2) (envelope-from ) id 1pCf9i-009LrI-Vt; Tue, 03 Jan 2023 12:08:30 +0100 From: Michael Olbrich To: ptxdist@pengutronix.de Date: Tue, 3 Jan 2023 12:08:30 +0100 Message-Id: <20230103110830.2228928-1-m.olbrich@pengutronix.de> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20221213132349.3082538-1-rhi@pengutronix.de> References: <20221213132349.3082538-1-rhi@pengutronix.de> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Subject: Re: [ptxdist] [APPLIED] 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 Thanks, applied as 0b95c2def4f5a600d634a158b54b5364f880b06b. Michael [sent from post-receive hook] On Tue, 03 Jan 2023 12:08:30 +0100, Roland Hieber wrote: > Signed-off-by: Roland Hieber > Message-Id: <20221213132349.3082538-1-rhi@pengutronix.de> > Signed-off-by: Michael Olbrich > > 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