Hi Heinrich, On Thu, 29 Dec 2022 at 22:08, Heinrich Schuchardt <[email protected]> wrote: > > Provide a man-page describing how to build the U-Boot documentation. > > Signed-off-by: Heinrich Schuchardt <[email protected]> > --- > 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 > + > +Infodoc documentation > +--------------------- > + > +The *infodocs* target builds both a texinfo and an info file: > + > +.. 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 infodocs > + # Deactivate the Python environment > + deactivate > + # Display the documentation > + info doc/output/texinfo/u-boot.info > + > +PDF documentation > +----------------- > + > +The *pdfdocs* target is meant to be used to build PDF documenation. > +As v2023.01 it fails with 'LaTeX Error: Too deeply nested'. > + > +We can use texi2pdf instead: > + > +.. 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 texinfodocs > + # Deactivate the Python environment > + deactivate > + # Convert to PDF > + texi2pdf doc/output/texinfo/u-boot.texi > + > +Texinfo documentation > +--------------------- > + > +To build only the texinfo documentation the *texinfodocs* target is used: > + > +.. 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 texinfodocs > + # Deactivate the Python environment > + deactivate > + > +The output is in file *doc/output/texinfo/u-boot.texi*. > diff --git a/doc/build/index.rst b/doc/build/index.rst > index 9a8105db21..dc9cde4001 100644 > --- a/doc/build/index.rst > +++ b/doc/build/index.rst > @@ -12,3 +12,4 @@ Build U-Boot > docker > tools > buildman > + documentation > -- > 2.37.2 > Regards, Simon
