[PATCH 1/1] doc: building documentation

[Heinrich Schuchardt]

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.

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 <sjg at chromium.org>
> 
> Regards,
> Simon