[PATCH 1/1] doc: building documentation

[Heinrich Schuchardt]

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