mailarchive of the ptxdist mailing list
 help / color / mirror / Atom feed
From: Roland Hieber <rhi@pengutronix.de>
To: ptxdist@pengutronix.de
Cc: Roland Hieber <rhi@pengutronix.de>
Subject: [ptxdist] [PATCH] doc: include instructions for layered documentation
Date: Tue, 13 Dec 2022 14:23:49 +0100	[thread overview]
Message-ID: <20221213132349.3082538-1-rhi@pengutronix.de> (raw)

Signed-off-by: Roland Hieber <rhi@pengutronix.de>
---
 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




             reply	other threads:[~2022-12-13 13:24 UTC|newest]

Thread overview: 4+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-12-13 13:23 Roland Hieber [this message]
2022-12-15  8:44 ` Michael Olbrich
2022-12-15 10:56   ` Roland Hieber
2023-01-03 11:08 ` [ptxdist] [APPLIED] " Michael Olbrich

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20221213132349.3082538-1-rhi@pengutronix.de \
    --to=rhi@pengutronix.de \
    --cc=ptxdist@pengutronix.de \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox