[PATCH 1/1] doc: building documentation

[Heinrich Schuchardt]

On 12/30/22 20:02, Simon Glass wrote:
> Hi,
> 
> On Fri, 30 Dec 2022 at 12:31, Heinrich Schuchardt
> <heinrich.schuchardt at 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 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.
> 
> 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.

Best regards

Heinrich