Hi Tom, On Sun, 8 Jan 2023 at 06:44, Tom Rini <[email protected]> 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 > > <[email protected]> wrote: > > > > > > > > > > > > On 1/7/23 23:54, Simon Glass wrote: > > > > Hi Heinrich, > > > > > > > > On Sat, 7 Jan 2023 at 15:16, Heinrich Schuchardt > > > > <[email protected]> wrote: > > > >> > > > >> > > > >> > > > >> On 1/7/23 19:55, Simon Glass wrote: > > > >>> Hi Heinrich, > > > >>> > > > >>> On Fri, 30 Dec 2022 at 12:08, Heinrich Schuchardt > > > >>> <[email protected]> wrote: > > > >>>> > > > >>>> > > > >>>> > > > >>>> On 12/30/22 20:02, Simon Glass wrote: > > > >>>>> Hi, > > > >>>>> > > > >>>>> On Fri, 30 Dec 2022 at 12:31, Heinrich Schuchardt > > > >>>>> <[email protected]> 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 > > > >>>>>>>> <[email protected]> wrote: > > > >>>>>>>>> > > > >>>>>>>>> Provide a man-page describing how to build the U-Boot > > > >>>>>>>>> documentation. > > > >>>>>>>>> > > > >>>>>>>>> Signed-off-by: Heinrich Schuchardt > > > >>>>>>>>> <[email protected]> > > > >>>>>>>>> --- > > > >>>>>>>>> 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
