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

2023-01-08 Thread Simon Glass 
Hi Tom,

On Sun, 8 Jan 2023 at 06:44, Tom Rini  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
> >  wrote:
> > >
> > >
> > >
> > > On 1/7/23 23:54, Simon Glass wrote:
> > > > Hi Heinrich,
> > > >
> > > > On Sat, 7 Jan 2023 at 15:16, Heinrich Schuchardt
> > > >  wrote:
> > > >>
> > > >>
> > > >>
> > > >> On 1/7/23 19:55, Simon Glass wrote:
> > > >>> Hi Heinrich,
> > > >>>
> > > >>> On Fri, 30 Dec 2022 at 12:08, Heinrich Schuchardt
> > > >>>  wrote:
> > > 
> > > 
> > > 
> > >  On 12/30/22 20:02, Simon Glass wrote:
> > > > Hi,
> > > >
> > > > On Fri, 30 Dec 2022 at 12:31, Heinrich Schuchardt
> > > >  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
> > >   wrote:
> > > >
> > > > Provide a man-page describing how to build the U-Boot 
> > > > documentation.
> > > >
> > > > Signed-off-by: Heinrich Schuchardt 
> > > > 
> > > > ---
> > > >  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 00..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 
> > > > `_.
> > > > +
> > > > +.. 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?
>

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

2023-01-08 Thread Tom Rini 
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
>  wrote:
> >
> >
> >
> > On 1/7/23 23:54, Simon Glass wrote:
> > > Hi Heinrich,
> > >
> > > On Sat, 7 Jan 2023 at 15:16, Heinrich Schuchardt
> > >  wrote:
> > >>
> > >>
> > >>
> > >> On 1/7/23 19:55, Simon Glass wrote:
> > >>> Hi Heinrich,
> > >>>
> > >>> On Fri, 30 Dec 2022 at 12:08, Heinrich Schuchardt
> > >>>  wrote:
> > 
> > 
> > 
> >  On 12/30/22 20:02, Simon Glass wrote:
> > > Hi,
> > >
> > > On Fri, 30 Dec 2022 at 12:31, Heinrich Schuchardt
> > >  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
> >   wrote:
> > >
> > > Provide a man-page describing how to build the U-Boot 
> > > documentation.
> > >
> > > Signed-off-by: Heinrich Schuchardt 
> > > 
> > > ---
> > >  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 00..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 
> > > `_.
> > > +
> > > +.. 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

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

2023-01-07 Thread Simon Glass 
Hi Heinrich,

On Sat, 7 Jan 2023 at 17:11, Heinrich Schuchardt
 wrote:
>
>
>
> On 1/7/23 23:54, Simon Glass wrote:
> > Hi Heinrich,
> >
> > On Sat, 7 Jan 2023 at 15:16, Heinrich Schuchardt
> >  wrote:
> >>
> >>
> >>
> >> On 1/7/23 19:55, Simon Glass wrote:
> >>> Hi Heinrich,
> >>>
> >>> On Fri, 30 Dec 2022 at 12:08, Heinrich Schuchardt
> >>>  wrote:
> 
> 
> 
>  On 12/30/22 20:02, Simon Glass wrote:
> > Hi,
> >
> > On Fri, 30 Dec 2022 at 12:31, Heinrich Schuchardt
> >  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
>   wrote:
> >
> > Provide a man-page describing how to build the U-Boot documentation.
> >
> > Signed-off-by: Heinrich Schuchardt 
> > 
> > ---
> >  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 00..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 
> > `_.
> > +
> > +.. 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

2023-01-07 Thread Heinrich Schuchardt 




On 1/7/23 23:54, Simon Glass wrote:

Hi Heinrich,

On Sat, 7 Jan 2023 at 15:16, Heinrich Schuchardt
 wrote:




On 1/7/23 19:55, Simon Glass wrote:

Hi Heinrich,

On Fri, 30 Dec 2022 at 12:08, Heinrich Schuchardt
 wrote:




On 12/30/22 20:02, Simon Glass wrote:

Hi,

On Fri, 30 Dec 2022 at 12:31, Heinrich Schuchardt
 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
 wrote:


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

Signed-off-by: Heinrich Schuchardt 
---
 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 00..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 
`_.
+
+.. 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

2023-01-07 Thread Simon Glass 
Hi Heinrich,

On Sat, 7 Jan 2023 at 15:16, Heinrich Schuchardt
 wrote:
>
>
>
> On 1/7/23 19:55, Simon Glass wrote:
> > Hi Heinrich,
> >
> > On Fri, 30 Dec 2022 at 12:08, Heinrich Schuchardt
> >  wrote:
> >>
> >>
> >>
> >> On 12/30/22 20:02, Simon Glass wrote:
> >>> Hi,
> >>>
> >>> On Fri, 30 Dec 2022 at 12:31, Heinrich Schuchardt
> >>>  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
> >>  wrote:
> >>>
> >>> Provide a man-page describing how to build the U-Boot documentation.
> >>>
> >>> Signed-off-by: Heinrich Schuchardt 
> >>> ---
> >>> 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 00..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 
> >>> `_.
> >>> +
> >>> +.. 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

2023-01-07 Thread Heinrich Schuchardt 




On 1/7/23 19:55, Simon Glass wrote:

Hi Heinrich,

On Fri, 30 Dec 2022 at 12:08, Heinrich Schuchardt
 wrote:




On 12/30/22 20:02, Simon Glass wrote:

Hi,

On Fri, 30 Dec 2022 at 12:31, Heinrich Schuchardt
 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
 wrote:


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

Signed-off-by: Heinrich Schuchardt 
---
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 00..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 
`_.
+
+.. 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 

Regards,
Simon

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

2023-01-07 Thread Tom Rini 
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
>  wrote:
> >
> >
> >
> > On 12/30/22 20:02, Simon Glass wrote:
> > > Hi,
> > >
> > > On Fri, 30 Dec 2022 at 12:31, Heinrich Schuchardt
> > >  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
> >   wrote:
> > >
> > > Provide a man-page describing how to build the U-Boot documentation.
> > >
> > > Signed-off-by: Heinrich Schuchardt 
> > > ---
> > >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 00..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 
> > > `_.
> > > +
> > > +.. 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


signature.asc
Description: PGP signature

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

2023-01-07 Thread Simon Glass 
Hi Heinrich,

On Fri, 30 Dec 2022 at 12:08, Heinrich Schuchardt
 wrote:
>
>
>
> On 12/30/22 20:02, Simon Glass wrote:
> > Hi,
> >
> > On Fri, 30 Dec 2022 at 12:31, Heinrich Schuchardt
> >  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
>   wrote:
> >
> > Provide a man-page describing how to build the U-Boot documentation.
> >
> > Signed-off-by: Heinrich Schuchardt 
> > ---
> >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 00..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 
> > `_.
> > +
> > +.. 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 

Regards,
Simon

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

2022-12-30 Thread Heinrich Schuchardt 




On 12/30/22 20:02, Simon Glass wrote:

Hi,

On Fri, 30 Dec 2022 at 12:31, Heinrich Schuchardt
 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
 wrote:


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

Signed-off-by: Heinrich Schuchardt 
---
   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 00..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 
`_.
+
+.. 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

2022-12-30 Thread Tom Rini 
On Fri, Dec 30, 2022 at 01:02:13PM -0600, Simon Glass wrote:
> Hi,
> 
> On Fri, 30 Dec 2022 at 12:31, Heinrich Schuchardt
>  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
> > >>  wrote:
> > >>>
> > >>> Provide a man-page describing how to build the U-Boot documentation.
> > >>>
> > >>> Signed-off-by: Heinrich Schuchardt 
> > >>> ---
> > >>>   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 00..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 
> > >>> `_.
> > >>> +
> > >>> +.. 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


signature.asc
Description: PGP signature

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

2022-12-30 Thread Simon Glass 
Hi,

On Fri, 30 Dec 2022 at 12:31, Heinrich Schuchardt
 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
> >>  wrote:
> >>>
> >>> Provide a man-page describing how to build the U-Boot documentation.
> >>>
> >>> Signed-off-by: Heinrich Schuchardt 
> >>> ---
> >>>   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 00..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 
> >>> `_.
> >>> +
> >>> +.. 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

2022-12-30 Thread 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
 wrote:


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

Signed-off-by: Heinrich Schuchardt 
---
  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 00..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 
`_.
+
+.. 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

2022-12-30 Thread Tom Rini 
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
>  wrote:
> >
> > Provide a man-page describing how to build the U-Boot documentation.
> >
> > Signed-off-by: Heinrich Schuchardt 
> > ---
> >  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 00..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 
> > `_.
> > +
> > +.. 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


signature.asc
Description: PGP signature

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

2022-12-30 Thread Simon Glass 
Hi Heinrich,

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

[PATCH 1/1] doc: building documentation

2022-12-29 Thread Heinrich Schuchardt 
Provide a man-page describing how to build the U-Boot documentation.

Signed-off-by: Heinrich Schuchardt 
---
 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 00..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 
`_.
+
+.. 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