On 1/7/23 23:54, Simon Glass wrote:
Hi Heinrich,
On Sat, 7 Jan 2023 at 15:16, Heinrich Schuchardt heinrich.schuchardt@canonical.com wrote:
On 1/7/23 19:55, 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.
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/
Best regards
Heinrich