[PATCH 1/1] doc: building documentation
Tom Rini
trini at konsulko.com
Fri Dec 30 19:12:10 CET 2022
On Fri, Dec 30, 2022 at 11:51:15AM -0600, Simon Glass wrote:
> Hi Heinrich,
>
> On Thu, 29 Dec 2022 at 22:08, Heinrich Schuchardt
> <heinrich.schuchardt at canonical.com> wrote:
> >
> > Provide a man-page describing how to build the U-Boot documentation.
> >
> > Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt at canonical.com>
> > ---
> > doc/build/documentation.rst | 90 +++++++++++++++++++++++++++++++++++++
> > doc/build/index.rst | 1 +
> > 2 files changed, 91 insertions(+)
> > create mode 100644 doc/build/documentation.rst
> >
> > diff --git a/doc/build/documentation.rst b/doc/build/documentation.rst
> > new file mode 100644
> > index 0000000000..896264dd7c
> > --- /dev/null
> > +++ b/doc/build/documentation.rst
> > @@ -0,0 +1,90 @@
> > +.. SPDX-License-Identifier: GPL-2.0+:
> > +
> > +Building documentation
> > +======================
> > +
> > +The U-Boot documentation is based on the Sphinx documentation generator.
> > +
> > +HTML documentation
> > +------------------
> > +
> > +The *htmldocs* target is used to build the HTML documentation. It uses the
> > +`Read the Docs Sphinx theme <https://sphinx-rtd-theme.readthedocs.io/en/stable/>`_.
> > +
> > +.. code-block:: bash
> > +
> > + # Create Python environment 'myenv'
> > + python3 -m venv myenv
> > + # Activate the Python environment
> > + . myenv/bin/activate
> > + # Install build requirements
> > + python3 -m pip install -r doc/sphinx/requirements.txt
> > + # Build the documentation
> > + make htmldocs
> > + # Deactivate the Python environment
> > + deactivate
> > + # Display the documentation in a graphical web browser
> > + x-www-browser doc/output/index.html
>
> If this is necessary then it is a bit of a sad indictment on Python. I
> would use:
>
> pip3 install -r doc/sphinx/requirements.txt
> make htmldocs
Which part, exactly? Using a virtual environment is I believe a normal
best practice and "python3 -m pip" rather than "pip3" I assume is
another best practice for portability. Then maybe the final step should
say "Review" not "Display" ?
--
Tom
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 659 bytes
Desc: not available
URL: <https://lists.denx.de/pipermail/u-boot/attachments/20221230/61963d9d/attachment.sig>
More information about the U-Boot
mailing list