Re: [PATCH 1/1] doc: building documentation

[Tom Rini <trini@konsulko.com>]

[-- Attachment #1: Type: text/plain, Size: 5214 bytes --]

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@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@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@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@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@canonical.com> wrote:
> > >>>>>>>>>
> > >>>>>>>>> Provide a man-page describing how to build the U-Boot documentation.
> > >>>>>>>>>
> > >>>>>>>>> Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@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.

-- 
Tom

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 659 bytes --]