[ptxdist] [PATCH] doc: include instructions for layered documentation

[ptxdist] [PATCH] doc: include instructions for layered documentation

[Roland Hieber]

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

Re: [ptxdist] [PATCH] doc: include instructions for layered documentation

[Michael Olbrich]

On Tue, Dec 13, 2022 at 02:23:49PM +0100, Roland Hieber wrote:
> 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*

This seems unrelated, or what am I missing here?

Michael

>     environment
>     user_manual_section
>     dev_manual
> -- 
> 2.30.2
> 
> 
> 

-- 
Pengutronix e.K.                           |                             |
Steuerwalder Str. 21                       | http://www.pengutronix.de/  |
31137 Hildesheim, Germany                  | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |

Re: [ptxdist] [PATCH] doc: include instructions for layered documentation

[Roland Hieber]

On Thu, Dec 15, 2022 at 09:44:50AM +0100, Michael Olbrich wrote:
> On Tue, Dec 13, 2022 at 02:23:49PM +0100, Roland Hieber wrote:
> > 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.

[here]

> > +
> > +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*
> 
> This seems unrelated, or what am I missing here?

welcome.rst has been moved into index-layer-0-ptxdist.rst; this is the
trick I described [here] above. This way the title page comes first,
then all the BSP-related documentation, then the PTXdist manual at the
end. I found it best to order it that way because people are probably
interested in the BSP-specific stuff more than the general stuff when
reading the BSP documentation.

 - Roland

> 
> Michael
> 
> >     environment
> >     user_manual_section
> >     dev_manual
> > -- 
> > 2.30.2
> > 
> > 
> > 
> 
> -- 
> Pengutronix e.K.                           |                             |
> Steuerwalder Str. 21                       | http://www.pengutronix.de/  |
> 31137 Hildesheim, Germany                  | Phone: +49-5121-206917-0    |
> Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |
> 

-- 
Roland Hieber, Pengutronix e.K.          | r.hieber@pengutronix.de     |
Steuerwalder Str. 21                     | https://www.pengutronix.de/ |
31137 Hildesheim, Germany                | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686         | Fax:   +49-5121-206917-5555 |

Re: [ptxdist] [APPLIED] doc: include instructions for layered documentation

[Michael Olbrich]

Thanks, applied as 0b95c2def4f5a600d634a158b54b5364f880b06b.

Michael

[sent from post-receive hook]

On Tue, 03 Jan 2023 12:08:30 +0100, Roland Hieber <rhi@pengutronix.de> wrote:
> Signed-off-by: Roland Hieber <rhi@pengutronix.de>
> Message-Id: <20221213132349.3082538-1-rhi@pengutronix.de>
> Signed-off-by: Michael Olbrich <m.olbrich@pengutronix.de>
> 
> 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