[PATCH 1/1] doc: building documentation

[Simon Glass]

Hi Tom,

On Sun, 8 Jan 2023 at 06:44, Tom Rini <trini at konsulko.com> wrote:
>
> On Sat, Jan 07, 2023 at 07:37:03PM -0700, Simon Glass wrote:
> > Hi Heinrich,
> >
> > On Sat, 7 Jan 2023 at 17:11, Heinrich Schuchardt
> > <heinrich.schuchardt at canonical.com> wrote:
> > >
> > >
> > >
> > > On 1/7/23 23:54, Simon Glass wrote:
> > > > 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?
> > >
> > > This is the output without Python environment:
> > > https://gist.github.com/xypron/aef88822a1f2f34e29faf5302313de6a
> > >
> > > This is what it should look like:
> > > https://u-boot.readthedocs.io/en/latest/
> >
> > Strangely, for me, it looks like the second thing even without the
> > environment. I have seen the first one though, but not for a while.I
> > vaguely remember installing some style package?
>
> See, stuff like this is why the virtualenv is the default and a python
> best practice. You don't have to guess why things randomly look
> different than expected (or even more fun, unexpectedly work) because
> everyone is on the same environment. Skipping virtualenv is a user
> beware kind of thing and not what we want to encourage.

Yes I do understand that. I have sent the review tag a while back.

It's just that it is so broken. This is the sort of thing that gives
Python a bad name...what is missing here that it shouldn't 'just
work'? Is it some sort of version conflict?

Regards,
Simon