[PATCH 1/1] doc: building documentation

[Simon Glass]

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


> +
> +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