[PATCH 1/1] doc: building documentation

[Tom Rini]

On Sat, Jan 07, 2023 at 11:55:59AM -0700, 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.
> 
> Would it be possible to have the virtual env start/stop stuff in a
> separate place? I suppose that would not be ideal either, since it
> would make the instructions more complicated for those that have
> trouble...

As virtualenv is a python best practice, I believe we should just assume
that users that want to skip it, know how to skip it.

-- 
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/20230107/da7c4c45/attachment.sig>