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.
Best regards
Heinrich
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
