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