[PATCH 1/1] doc: building documentation

[Simon Glass]

Hi Heinrich,

On Sat, 7 Jan 2023 at 15:16, Heinrich Schuchardt
<heinrich.schuchardt at canonical.com> wrote:
>
>
>
> On 1/7/23 19:55, Simon Glass wrote:
> > Hi Heinrich,
> >
> > On Fri, 30 Dec 2022 at 12:08, Heinrich Schuchardt
> > <heinrich.schuchardt at canonical.com> wrote:
> >>
> >>
> >>
> >> On 12/30/22 20:02, Simon Glass wrote:
> >>> 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?
> >>
> >> Current Ubuntu packages are incompatible with the readthedocs theme.
> >> Therefore I describe a way of building that works for most users.
> >
> > OK I see. Somehow it builds OK for me on 22.04 but I have not tried
> > newer versions.
>
> make htmldocs builds but the formatting of the HTML does not conform to
> the readthedocs style. Just open the documentation in a browser.

It looks OK for me...what should I be seeing?

Regards,
Simon