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. Would it be possible to have the virtual env start/stop stuff in a separate place? I suppose that would not be ideal either, since it would make the instructions more complicated for those that have trouble... Reviewed-by: Simon Glass <[email protected]> Regards, Simon
