* [ptxdist] [PATCH] doc: include instructions for layered documentation @ 2022-12-13 13:23 Roland Hieber 2022-12-15 8:44 ` Michael Olbrich 2023-01-03 11:08 ` [ptxdist] [APPLIED] " Michael Olbrich 0 siblings, 2 replies; 4+ messages in thread From: Roland Hieber @ 2022-12-13 13:23 UTC (permalink / raw) To: ptxdist; +Cc: 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 ^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [ptxdist] [PATCH] doc: include instructions for layered documentation 2022-12-13 13:23 [ptxdist] [PATCH] doc: include instructions for layered documentation Roland Hieber @ 2022-12-15 8:44 ` Michael Olbrich 2022-12-15 10:56 ` Roland Hieber 2023-01-03 11:08 ` [ptxdist] [APPLIED] " Michael Olbrich 1 sibling, 1 reply; 4+ messages in thread From: Michael Olbrich @ 2022-12-15 8:44 UTC (permalink / raw) To: Roland Hieber, ptxdist 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 | ^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [ptxdist] [PATCH] doc: include instructions for layered documentation 2022-12-15 8:44 ` Michael Olbrich @ 2022-12-15 10:56 ` Roland Hieber 0 siblings, 0 replies; 4+ messages in thread From: Roland Hieber @ 2022-12-15 10:56 UTC (permalink / raw) To: ptxdist 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 | ^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [ptxdist] [APPLIED] doc: include instructions for layered documentation 2022-12-13 13:23 [ptxdist] [PATCH] doc: include instructions for layered documentation Roland Hieber 2022-12-15 8:44 ` Michael Olbrich @ 2023-01-03 11:08 ` Michael Olbrich 1 sibling, 0 replies; 4+ messages in thread From: Michael Olbrich @ 2023-01-03 11:08 UTC (permalink / raw) To: ptxdist; +Cc: Roland Hieber 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 ^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2023-01-03 11:09 UTC | newest] Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2022-12-13 13:23 [ptxdist] [PATCH] doc: include instructions for layered documentation Roland Hieber 2022-12-15 8:44 ` Michael Olbrich 2022-12-15 10:56 ` Roland Hieber 2023-01-03 11:08 ` [ptxdist] [APPLIED] " Michael Olbrich
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox