* [PATCH 1/1] doc: building documentation @ 2022-12-30 4:07 Heinrich Schuchardt 2022-12-30 17:51 ` Simon Glass 0 siblings, 1 reply; 15+ messages in thread From: Heinrich Schuchardt @ 2022-12-30 4:07 UTC (permalink / raw) To: Tom Rini; +Cc: Maxim Cournoyer, u-boot, 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 ^ permalink raw reply related [flat|nested] 15+ messages in thread
* Re: [PATCH 1/1] doc: building documentation 2022-12-30 4:07 [PATCH 1/1] doc: building documentation Heinrich Schuchardt @ 2022-12-30 17:51 ` Simon Glass 2022-12-30 18:12 ` Tom Rini 0 siblings, 1 reply; 15+ messages in thread From: Simon Glass @ 2022-12-30 17:51 UTC (permalink / raw) To: Heinrich Schuchardt; +Cc: Tom Rini, Maxim Cournoyer, u-boot 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH 1/1] doc: building documentation 2022-12-30 17:51 ` Simon Glass @ 2022-12-30 18:12 ` Tom Rini 2022-12-30 18:31 ` Heinrich Schuchardt 0 siblings, 1 reply; 15+ messages in thread From: Tom Rini @ 2022-12-30 18:12 UTC (permalink / raw) To: Simon Glass; +Cc: Heinrich Schuchardt, Maxim Cournoyer, u-boot [-- 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 --] ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH 1/1] doc: building documentation 2022-12-30 18:12 ` Tom Rini @ 2022-12-30 18:31 ` Heinrich Schuchardt 2022-12-30 19:02 ` Simon Glass 0 siblings, 1 reply; 15+ messages in thread From: Heinrich Schuchardt @ 2022-12-30 18:31 UTC (permalink / raw) To: Tom Rini; +Cc: Maxim Cournoyer, u-boot, Simon Glass 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH 1/1] doc: building documentation 2022-12-30 18:31 ` Heinrich Schuchardt @ 2022-12-30 19:02 ` Simon Glass 2022-12-30 19:08 ` Tom Rini 2022-12-30 19:08 ` Heinrich Schuchardt 0 siblings, 2 replies; 15+ messages in thread From: Simon Glass @ 2022-12-30 19:02 UTC (permalink / raw) To: Heinrich Schuchardt; +Cc: Tom Rini, Maxim Cournoyer, u-boot 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH 1/1] doc: building documentation 2022-12-30 19:02 ` Simon Glass @ 2022-12-30 19:08 ` Tom Rini 2022-12-30 19:08 ` Heinrich Schuchardt 1 sibling, 0 replies; 15+ messages in thread From: Tom Rini @ 2022-12-30 19:08 UTC (permalink / raw) To: Simon Glass; +Cc: Heinrich Schuchardt, Maxim Cournoyer, u-boot [-- 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 --] ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH 1/1] doc: building documentation 2022-12-30 19:02 ` Simon Glass 2022-12-30 19:08 ` Tom Rini @ 2022-12-30 19:08 ` Heinrich Schuchardt 2023-01-07 18:55 ` Simon Glass 1 sibling, 1 reply; 15+ messages in thread From: Heinrich Schuchardt @ 2022-12-30 19:08 UTC (permalink / raw) To: Simon Glass; +Cc: Tom Rini, Maxim Cournoyer, u-boot 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH 1/1] doc: building documentation 2022-12-30 19:08 ` Heinrich Schuchardt @ 2023-01-07 18:55 ` Simon Glass 2023-01-07 19:09 ` Tom Rini 2023-01-07 22:16 ` Heinrich Schuchardt 0 siblings, 2 replies; 15+ messages in thread From: Simon Glass @ 2023-01-07 18:55 UTC (permalink / raw) To: Heinrich Schuchardt; +Cc: Tom Rini, Maxim Cournoyer, u-boot 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH 1/1] doc: building documentation 2023-01-07 18:55 ` Simon Glass @ 2023-01-07 19:09 ` Tom Rini 2023-01-07 22:16 ` Heinrich Schuchardt 1 sibling, 0 replies; 15+ messages in thread From: Tom Rini @ 2023-01-07 19:09 UTC (permalink / raw) To: Simon Glass; +Cc: Heinrich Schuchardt, Maxim Cournoyer, u-boot [-- 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 --] ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH 1/1] doc: building documentation 2023-01-07 18:55 ` Simon Glass 2023-01-07 19:09 ` Tom Rini @ 2023-01-07 22:16 ` Heinrich Schuchardt 2023-01-07 22:54 ` Simon Glass 1 sibling, 1 reply; 15+ messages in thread From: Heinrich Schuchardt @ 2023-01-07 22:16 UTC (permalink / raw) To: Simon Glass; +Cc: Tom Rini, Maxim Cournoyer, u-boot 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH 1/1] doc: building documentation 2023-01-07 22:16 ` Heinrich Schuchardt @ 2023-01-07 22:54 ` Simon Glass 2023-01-08 0:11 ` Heinrich Schuchardt 0 siblings, 1 reply; 15+ messages in thread From: Simon Glass @ 2023-01-07 22:54 UTC (permalink / raw) To: Heinrich Schuchardt; +Cc: Tom Rini, Maxim Cournoyer, u-boot 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH 1/1] doc: building documentation 2023-01-07 22:54 ` Simon Glass @ 2023-01-08 0:11 ` Heinrich Schuchardt 2023-01-08 2:37 ` Simon Glass 0 siblings, 1 reply; 15+ messages in thread From: Heinrich Schuchardt @ 2023-01-08 0:11 UTC (permalink / raw) To: Simon Glass; +Cc: Tom Rini, Maxim Cournoyer, u-boot 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH 1/1] doc: building documentation 2023-01-08 0:11 ` Heinrich Schuchardt @ 2023-01-08 2:37 ` Simon Glass 2023-01-08 13:44 ` Tom Rini 0 siblings, 1 reply; 15+ messages in thread From: Simon Glass @ 2023-01-08 2:37 UTC (permalink / raw) To: Heinrich Schuchardt; +Cc: Tom Rini, Maxim Cournoyer, u-boot 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH 1/1] doc: building documentation 2023-01-08 2:37 ` Simon Glass @ 2023-01-08 13:44 ` Tom Rini 2023-01-08 15:05 ` Simon Glass 0 siblings, 1 reply; 15+ messages in thread From: Tom Rini @ 2023-01-08 13:44 UTC (permalink / raw) To: Simon Glass; +Cc: Heinrich Schuchardt, Maxim Cournoyer, u-boot [-- 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 --] ^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH 1/1] doc: building documentation 2023-01-08 13:44 ` Tom Rini @ 2023-01-08 15:05 ` Simon Glass 0 siblings, 0 replies; 15+ messages in thread From: Simon Glass @ 2023-01-08 15:05 UTC (permalink / raw) To: Tom Rini; +Cc: Heinrich Schuchardt, Maxim Cournoyer, u-boot 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 ^ permalink raw reply [flat|nested] 15+ messages in thread
end of thread, other threads:[~2023-01-08 15:06 UTC | newest] Thread overview: 15+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2022-12-30 4:07 [PATCH 1/1] doc: building documentation Heinrich Schuchardt 2022-12-30 17:51 ` Simon Glass 2022-12-30 18:12 ` Tom Rini 2022-12-30 18:31 ` Heinrich Schuchardt 2022-12-30 19:02 ` Simon Glass 2022-12-30 19:08 ` Tom Rini 2022-12-30 19:08 ` Heinrich Schuchardt 2023-01-07 18:55 ` Simon Glass 2023-01-07 19:09 ` Tom Rini 2023-01-07 22:16 ` Heinrich Schuchardt 2023-01-07 22:54 ` Simon Glass 2023-01-08 0:11 ` Heinrich Schuchardt 2023-01-08 2:37 ` Simon Glass 2023-01-08 13:44 ` Tom Rini 2023-01-08 15:05 ` Simon Glass
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.