[PATCH 1/1] doc: building documentation

[Heinrich Schuchardt]

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 at canonical.com> wrote:
>>>
>>> Provide a man-page describing how to build the U-Boot documentation.
>>>
>>> Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt at 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.

Best regards

Heinrich