From: Roland Hieber <rhi@pengutronix.de>
To: ptxdist@pengutronix.de
Subject: Re: [ptxdist] [PATCH] doc: include instructions for layered documentation
Date: Thu, 15 Dec 2022 11:56:30 +0100 [thread overview]
Message-ID: <20221215105630.5j75qj3m72fvkqez@pengutronix.de> (raw)
In-Reply-To: <Y5regjxkdNVfae1c@pengutronix.de>
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 |
next prev parent reply other threads:[~2022-12-15 10:56 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-12-13 13:23 Roland Hieber
2022-12-15 8:44 ` Michael Olbrich
2022-12-15 10:56 ` Roland Hieber [this message]
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=20221215105630.5j75qj3m72fvkqez@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