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