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? Regards, Simon
