[PATCH 1/1] doc: building documentation

[PATCH 1/1] doc: building documentation

[Heinrich Schuchardt]

Provide a man-page describing how to build the U-Boot documentation.

Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@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
+
+Infodoc documentation
+---------------------
+
+The *infodocs* target builds both a texinfo and an info file:
+
+.. 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 infodocs
+    # Deactivate the Python environment
+    deactivate
+    # Display the documentation
+    info doc/output/texinfo/u-boot.info
+
+PDF documentation
+-----------------
+
+The *pdfdocs* target is meant to be used to build PDF documenation.
+As v2023.01 it fails with 'LaTeX Error: Too deeply nested'.
+
+We can use texi2pdf instead:
+
+.. 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 texinfodocs
+    # Deactivate the Python environment
+    deactivate
+    # Convert to PDF
+    texi2pdf doc/output/texinfo/u-boot.texi
+
+Texinfo documentation
+---------------------
+
+To build only the texinfo documentation the *texinfodocs* target is used:
+
+.. 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 texinfodocs
+    # Deactivate the Python environment
+    deactivate
+
+The output is in file *doc/output/texinfo/u-boot.texi*.
diff --git a/doc/build/index.rst b/doc/build/index.rst
index 9a8105db21..dc9cde4001 100644
--- a/doc/build/index.rst
+++ b/doc/build/index.rst
@@ -12,3 +12,4 @@ Build U-Boot
    docker
    tools
    buildman
+   documentation
-- 
2.37.2

Re: [PATCH 1/1] doc: building documentation

[Simon Glass]

Hi Heinrich,

On Thu, 29 Dec 2022 at 22:08, Heinrich Schuchardt
<heinrich.schuchardt@canonical.com> wrote:
>
> Provide a man-page describing how to build the U-Boot documentation.
>
> Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@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


> +
> +Infodoc documentation
> +---------------------
> +
> +The *infodocs* target builds both a texinfo and an info file:
> +
> +.. 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 infodocs
> +    # Deactivate the Python environment
> +    deactivate
> +    # Display the documentation
> +    info doc/output/texinfo/u-boot.info
> +
> +PDF documentation
> +-----------------
> +
> +The *pdfdocs* target is meant to be used to build PDF documenation.
> +As v2023.01 it fails with 'LaTeX Error: Too deeply nested'.
> +
> +We can use texi2pdf instead:
> +
> +.. 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 texinfodocs
> +    # Deactivate the Python environment
> +    deactivate
> +    # Convert to PDF
> +    texi2pdf doc/output/texinfo/u-boot.texi
> +
> +Texinfo documentation
> +---------------------
> +
> +To build only the texinfo documentation the *texinfodocs* target is used:
> +
> +.. 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 texinfodocs
> +    # Deactivate the Python environment
> +    deactivate
> +
> +The output is in file *doc/output/texinfo/u-boot.texi*.
> diff --git a/doc/build/index.rst b/doc/build/index.rst
> index 9a8105db21..dc9cde4001 100644
> --- a/doc/build/index.rst
> +++ b/doc/build/index.rst
> @@ -12,3 +12,4 @@ Build U-Boot
>     docker
>     tools
>     buildman
> +   documentation
> --
> 2.37.2
>

Regards,
Simon

Re: [PATCH 1/1] doc: building documentation

[Tom Rini]

[-- Attachment #1: Type: text/plain, Size: 2163 bytes --]

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

-- 
Tom

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 659 bytes --]

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

Re: [PATCH 1/1] doc: building documentation

[Simon Glass]

Hi,

On Fri, 30 Dec 2022 at 12:31, Heinrich Schuchardt
<heinrich.schuchardt@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@canonical.com> wrote:
> >>>
> >>> Provide a man-page describing how to build the U-Boot documentation.
> >>>
> >>> Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@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?

Regards,
Simon

Re: [PATCH 1/1] doc: building documentation

[Tom Rini]

[-- Attachment #1: Type: text/plain, Size: 3062 bytes --]

On Fri, Dec 30, 2022 at 01:02:13PM -0600, Simon Glass wrote:
> Hi,
> 
> On Fri, 30 Dec 2022 at 12:31, Heinrich Schuchardt
> <heinrich.schuchardt@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@canonical.com> wrote:
> > >>>
> > >>> Provide a man-page describing how to build the U-Boot documentation.
> > >>>
> > >>> Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@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?

I think that's the opposite.  As best I can see, virtual environments
are a python best practice, and if you don't want to use one you just
skip those steps.

-- 
Tom

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 659 bytes --]

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

Re: [PATCH 1/1] doc: building documentation

[Simon Glass]

Hi Heinrich,

On Fri, 30 Dec 2022 at 12:08, Heinrich Schuchardt
<heinrich.schuchardt@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@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@canonical.com> wrote:
> >>>>>
> >>>>> Provide a man-page describing how to build the U-Boot documentation.
> >>>>>
> >>>>> Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@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.

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@chromium.org>

Regards,
Simon

Re: [PATCH 1/1] doc: building documentation

[Tom Rini]

[-- Attachment #1: Type: text/plain, Size: 3848 bytes --]

On Sat, Jan 07, 2023 at 11:55:59AM -0700, Simon Glass wrote:
> Hi Heinrich,
> 
> On Fri, 30 Dec 2022 at 12:08, Heinrich Schuchardt
> <heinrich.schuchardt@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@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@canonical.com> wrote:
> > >>>>>
> > >>>>> Provide a man-page describing how to build the U-Boot documentation.
> > >>>>>
> > >>>>> Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@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.
> 
> 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...

As virtualenv is a python best practice, I believe we should just assume
that users that want to skip it, know how to skip it.

-- 
Tom

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 659 bytes --]

Re: [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@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@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@canonical.com> wrote:
>>>>>>>
>>>>>>> Provide a man-page describing how to build the U-Boot documentation.
>>>>>>>
>>>>>>> Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@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@chromium.org>
> 
> Regards,
> Simon

Re: [PATCH 1/1] doc: building documentation

[Simon Glass]

Hi Heinrich,

On Sat, 7 Jan 2023 at 15:16, Heinrich Schuchardt
<heinrich.schuchardt@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@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@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@canonical.com> wrote:
> >>>>>>>
> >>>>>>> Provide a man-page describing how to build the U-Boot documentation.
> >>>>>>>
> >>>>>>> Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@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?

Regards,
Simon

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

Re: [PATCH 1/1] doc: building documentation

[Simon Glass]

Hi Heinrich,

On Sat, 7 Jan 2023 at 17:11, Heinrich Schuchardt
<heinrich.schuchardt@canonical.com> wrote:
>
>
>
> On 1/7/23 23:54, Simon Glass wrote:
> > Hi Heinrich,
> >
> > On Sat, 7 Jan 2023 at 15:16, Heinrich Schuchardt
> > <heinrich.schuchardt@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@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@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@canonical.com> wrote:
> >>>>>>>>>
> >>>>>>>>> Provide a man-page describing how to build the U-Boot documentation.
> >>>>>>>>>
> >>>>>>>>> Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@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/

Strangely, for me, it looks like the second thing even without the
environment. I have seen the first one though, but not for a while.I
vaguely remember installing some style package?

Regards,
Simon

Re: [PATCH 1/1] doc: building documentation

[Tom Rini]

[-- Attachment #1: Type: text/plain, Size: 5214 bytes --]

On Sat, Jan 07, 2023 at 07:37:03PM -0700, Simon Glass wrote:
> Hi Heinrich,
> 
> On Sat, 7 Jan 2023 at 17:11, Heinrich Schuchardt
> <heinrich.schuchardt@canonical.com> wrote:
> >
> >
> >
> > On 1/7/23 23:54, Simon Glass wrote:
> > > Hi Heinrich,
> > >
> > > On Sat, 7 Jan 2023 at 15:16, Heinrich Schuchardt
> > > <heinrich.schuchardt@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@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@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@canonical.com> wrote:
> > >>>>>>>>>
> > >>>>>>>>> Provide a man-page describing how to build the U-Boot documentation.
> > >>>>>>>>>
> > >>>>>>>>> Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@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/
> 
> Strangely, for me, it looks like the second thing even without the
> environment. I have seen the first one though, but not for a while.I
> vaguely remember installing some style package?

See, stuff like this is why the virtualenv is the default and a python
best practice. You don't have to guess why things randomly look
different than expected (or even more fun, unexpectedly work) because
everyone is on the same environment. Skipping virtualenv is a user
beware kind of thing and not what we want to encourage.

-- 
Tom

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 659 bytes --]

Re: [PATCH 1/1] doc: building documentation

[Simon Glass]

Hi Tom,

On Sun, 8 Jan 2023 at 06:44, Tom Rini <trini@konsulko.com> wrote:
>
> On Sat, Jan 07, 2023 at 07:37:03PM -0700, Simon Glass wrote:
> > Hi Heinrich,
> >
> > On Sat, 7 Jan 2023 at 17:11, Heinrich Schuchardt
> > <heinrich.schuchardt@canonical.com> wrote:
> > >
> > >
> > >
> > > On 1/7/23 23:54, Simon Glass wrote:
> > > > Hi Heinrich,
> > > >
> > > > On Sat, 7 Jan 2023 at 15:16, Heinrich Schuchardt
> > > > <heinrich.schuchardt@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@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@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@canonical.com> wrote:
> > > >>>>>>>>>
> > > >>>>>>>>> Provide a man-page describing how to build the U-Boot documentation.
> > > >>>>>>>>>
> > > >>>>>>>>> Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@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/
> >
> > Strangely, for me, it looks like the second thing even without the
> > environment. I have seen the first one though, but not for a while.I
> > vaguely remember installing some style package?
>
> See, stuff like this is why the virtualenv is the default and a python
> best practice. You don't have to guess why things randomly look
> different than expected (or even more fun, unexpectedly work) because
> everyone is on the same environment. Skipping virtualenv is a user
> beware kind of thing and not what we want to encourage.

Yes I do understand that. I have sent the review tag a while back.

It's just that it is so broken. This is the sort of thing that gives
Python a bad name...what is missing here that it shouldn't 'just
work'? Is it some sort of version conflict?

Regards,
Simon