[PATCH 1/1] doc: building documentation

[Simon Glass]

Hi,

On Fri, 30 Dec 2022 at 12:31, Heinrich Schuchardt
<heinrich.schuchardt at canonical.com> wrote:
>
>
>
> On 12/30/22 19:12, Tom Rini wrote:
> > 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" ?
> >
>
> Review only applies to documentation developers.
> Normal users just want to read the documentation.

Using a virtual environment seems annoying to me. Should we put that
in a separate section for those who want to do it?

Regards,
Simon