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