On Sat, Jan 07, 2023 at 11:55:59AM -0700, Simon Glass wrote:
Hi Heinrich,
On Fri, 30 Dec 2022 at 12:08, Heinrich Schuchardt heinrich.schuchardt@canonical.com wrote:
On 12/30/22 20:02, Simon Glass wrote:
Hi,
On Fri, 30 Dec 2022 at 12:31, Heinrich Schuchardt heinrich.schuchardt@canonical.com 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 heinrich.schuchardt@canonical.com wrote: > > Provide a man-page describing how to build the U-Boot documentation. > > Signed-off-by: Heinrich Schuchardt heinrich.schuchardt@canonical.com > --- > 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...
As virtualenv is a python best practice, I believe we should just assume that users that want to skip it, know how to skip it.