Skip to contentSkip to conversation

documentation/README: refer to doc package requirements

PATCH In review [email protected] 2 participants 4 messages Jun 11, 2024 – Jun 19, 2024

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 documentation/README: refer to doc package requirements

From: Michael Opdenacker <[email protected]>

Refer to package requirements for building documentation from supported distributions. The simple instructions previously listed no longer work on Ubuntu 24.04, for example.

---
 documentation/README | 29 +++--------------------------
 1 file changed, 3 insertions(+), 26 deletions(-)
documentation/README +3 -26
index b60472fcbf..c888b666a8 100644
@@ -108,32 +108,9 @@ generated with DocBook.
 How to build the Yocto Project documentation
 ============================================
 
-Sphinx is written in Python. While it might work with Python2, for
-obvious reasons, we will only support building the Yocto Project
-documentation with Python3.
-
-Sphinx might be available in your Linux distro packages repositories,
-however it is not recommended to use distro packages, as they might be
-old versions, especially if you are using an LTS version of your
-distro. The recommended method to install the latest versions of Sphinx
-and of its required dependencies is to use the Python Package Index (pip).
-
-To install all required packages run:
-
- $ pip3 install sphinx sphinx_rtd_theme pyyaml
-
-To make sure you always have the latest versions of such packages, you
-should regularly run the same command with an added "--upgrade" option:
-
- $ pip3 install --upgrade sphinx sphinx_rtd_theme pyyaml
-
-Also install the "inkscape" package from your distribution.
-Inkscape is need to convert SVG graphics to PNG (for EPUB
-export) and to PDF (for PDF export).
-
-Additionally install "fncychap.sty" TeX font if you want to build PDFs. Debian
-and Ubuntu have it in "texlive-latex-extra" package while RedHat distributions
-and OpenSUSE have it in "texlive-fncychap" package for example.
+To build the documentation, you need Sphinx and a few other packages,
+which depend on your host GNU/Linux distribution. Such packages are listed on
+https://docs.yoctoproject.org/dev/ref-manual/system-requirements.html#required-packages-for-the-build-host
 
 To build the documentation locally, run:
 
Reviewed-by on v1 1/1
#1 lore raw

Hi Michael,

Quoted 39 lines · Michael Opdenacker via lists.yoctoproject.org

From: Michael Opdenacker <[email protected]>

Refer to package requirements for building documentation from supported distributions. The simple instructions previously listed no longer work on Ubuntu 24.04, for example.

---
  documentation/README | 29 +++--------------------------
  1 file changed, 3 insertions(+), 26 deletions(-)
documentation/README +0 -20
index b60472fcbf..c888b666a8 100644
@@ -108,32 +108,9 @@ generated with DocBook.
  How to build the Yocto Project documentation
  ============================================
 
-Sphinx is written in Python. While it might work with Python2, for
-obvious reasons, we will only support building the Yocto Project
-documentation with Python3.
-
-Sphinx might be available in your Linux distro packages repositories,
-however it is not recommended to use distro packages, as they might be
-old versions, especially if you are using an LTS version of your
-distro. The recommended method to install the latest versions of Sphinx
-and of its required dependencies is to use the Python Package Index (pip).
-
-To install all required packages run:
-
- $ pip3 install sphinx sphinx_rtd_theme pyyaml
-
-To make sure you always have the latest versions of such packages, you
-should regularly run the same command with an added "--upgrade" option:
-
- $ pip3 install --upgrade sphinx sphinx_rtd_theme pyyaml
-
-Also install the "inkscape" package from your distribution.

documentation/README generated with DocBook. · line 114

Quoted 10 lines
documentation/README +3 -6
-Inkscape is need to convert SVG graphics to PNG (for EPUB
-export) and to PDF (for PDF export).
-
-Additionally install "fncychap.sty" TeX font if you want to build PDFs. Debian
-and Ubuntu have it in "texlive-latex-extra" package while RedHat distributions
-and OpenSUSE have it in "texlive-fncychap" package for example.
+To build the documentation, you need Sphinx and a few other packages,
+which depend on your host GNU/Linux distribution. Such packages are listed on
+https://docs.yoctoproject.org/dev/ref-manual/system-requirements.html#required-packages-for-the-build-host
 

This points to the latest commit in the master branch and not necessarily the one which contains the appropriate instructions for the version of the yocto-docs one currently has checked out. We could point at documentation/ref-manual/system-requirements.rst and PIP3_HOST_PACKAGES in documentation/poky.yaml.in though but not sure it makes it easier to know what to do. A bit of a chicken and the egg problem as to get a simple up-to-date instruction on how to build the docs, you need the docs built.

In any case, this needs fixing, so

Thanks!
Quentin

#2 lore raw

Hi Quentin,

Thanks for the review!

Quoted 49 lines · Quentin Schulz via lists.yoctoproject.org

Hi Michael,

Quoted 46 lines · Michael Opdenacker via lists.yoctoproject.org

From: Michael Opdenacker <[email protected]>

Refer to package requirements for building documentation from supported distributions. The simple instructions previously listed no longer work on Ubuntu 24.04, for example.

---
  documentation/README | 29 +++--------------------------

  1 file changed, 3 insertions(+), 26 deletions(-)
documentation/README +0 -0
index b60472fcbf..c888b666a8 100644
@@ -108,32 +108,9 @@ generated with DocBook.

  How to build the Yocto Project documentation
  ============================================
  -Sphinx is written in Python. While it might work with Python2, for

documentation/README +0 -8
-obvious reasons, we will only support building the Yocto Project
-documentation with Python3.
-
-Sphinx might be available in your Linux distro packages repositories,
-however it is not recommended to use distro packages, as they might be
-old versions, especially if you are using an LTS version of your
-distro. The recommended method to install the latest versions of Sphinx
-and of its required dependencies is to use the Python Package Index 

(pip).

documentation/README +0 -15
-
-To install all required packages run:
-
- $ pip3 install sphinx sphinx_rtd_theme pyyaml
-
-To make sure you always have the latest versions of such packages, you
-should regularly run the same command with an added "--upgrade" option:
-
- $ pip3 install --upgrade sphinx sphinx_rtd_theme pyyaml
-
-Also install the "inkscape" package from your distribution.
-Inkscape is need to convert SVG graphics to PNG (for EPUB
-export) and to PDF (for PDF export).
-
-Additionally install "fncychap.sty" TeX font if you want to build 

PDFs. Debian
-and Ubuntu have it in "texlive-latex-extra" package while RedHat distributions

Quoted 8 lines
Quoted 6 lines
documentation/README +2 -1
-and OpenSUSE have it in "texlive-fncychap" package for example.
+To build the documentation, you need Sphinx and a few other packages,
+which depend on your host GNU/Linux distribution. Such packages are 

listed on +https://docs.yoctoproject.org/dev/ref-manual/system-requirements.html#required-packages-for-the-build-host

This points to the latest commit in the master branch and not necessarily the one which contains the appropriate instructions for the version of the yocto-docs one currently has checked out. We could point at documentation/ref-manual/system-requirements.rst and PIP3_HOST_PACKAGES in documentation/poky.yaml.in though but not sure it makes it easier to know what to do. A bit of a chicken and the egg problem as to get a simple up-to-date instruction on how to build the docs, you need the docs built.

You have a point. Maybe just pointing to the production version of the docs (https://docs.yoctoproject.org/ref-manual/system-requirements.html#required-packages-for-the-build-host) would be a acceptable compromise. This way, people don't have to build the docs to know how to build them, and then can then use the version switcher menu to find the docs that match their particular version.

What do you think?
Cheers
Michael.

#3 lore raw

Hi Michael,

Quoted 63 lines · Michael Opdenacker via lists.yoctoproject.org

Hi Quentin,

Thanks for the review!

Quoted 48 lines · Quentin Schulz via lists.yoctoproject.org

Hi Michael,

Quoted 45 lines · Michael Opdenacker via lists.yoctoproject.org

From: Michael Opdenacker <[email protected]>

Refer to package requirements for building documentation from supported distributions. The simple instructions previously listed no longer work on Ubuntu 24.04, for example.

---
  documentation/README | 29 +++--------------------------

  1 file changed, 3 insertions(+), 26 deletions(-)
documentation/README +0 -0
index b60472fcbf..c888b666a8 100644
@@ -108,32 +108,9 @@ generated with DocBook.

  How to build the Yocto Project documentation
  ============================================
  -Sphinx is written in Python. While it might work with Python2, for

documentation/README +0 -8
-obvious reasons, we will only support building the Yocto Project
-documentation with Python3.
-
-Sphinx might be available in your Linux distro packages repositories,
-however it is not recommended to use distro packages, as they might be
-old versions, especially if you are using an LTS version of your
-distro. The recommended method to install the latest versions of Sphinx
-and of its required dependencies is to use the Python Package Index 

(pip).

documentation/README +0 -15
-
-To install all required packages run:
-
- $ pip3 install sphinx sphinx_rtd_theme pyyaml
-
-To make sure you always have the latest versions of such packages, you
-should regularly run the same command with an added "--upgrade" option:
-
- $ pip3 install --upgrade sphinx sphinx_rtd_theme pyyaml
-
-Also install the "inkscape" package from your distribution.
-Inkscape is need to convert SVG graphics to PNG (for EPUB
-export) and to PDF (for PDF export).
-
-Additionally install "fncychap.sty" TeX font if you want to build 

PDFs. Debian
-and Ubuntu have it in "texlive-latex-extra" package while RedHat

Quoted 8 lines
Quoted 6 lines

distributions

documentation/README +2 -1
-and OpenSUSE have it in "texlive-fncychap" package for example.
+To build the documentation, you need Sphinx and a few other packages,
+which depend on your host GNU/Linux distribution. Such packages are 

listed on +https://docs.yoctoproject.org/dev/ref-manual/system-requirements.html#required-packages-for-the-build-host

This points to the latest commit in the master branch and not necessarily the one which contains the appropriate instructions for the version of the yocto-docs one currently has checked out. We could point at documentation/ref-manual/system-requirements.rst and PIP3_HOST_PACKAGES in documentation/poky.yaml.in though but not sure it makes it easier to know what to do. A bit of a chicken and the egg problem as to get a simple up-to-date instruction on how to build the docs, you need the docs built.

Quoted 2 lines

You have a point. Maybe just pointing to the production version of the docs (https://docs.yoctoproject.org/ref-manual/system-requirements.html#required-packages-for-the-build-host) would be a acceptable compromise. This way, people don't have to build the docs to know how to build them, and then can then use the version switcher menu to find the docs that match their particular version.

I guess we can still keep dev/. I just didn't like too much to point at some URL which is bound to be not relevant to the current state of the yocto-docs repo. The alternative I suggested isn't really user-friendly either. So I guess we can just pick the one that has the less friction albeit maybe outdated/not applicable, so we can just keep the link.

I realize that "In any case, this needs fixing, so" could be understood different ways. What I meant is that the current info in the README needs to be fixed, and your patch is one way to do it, so I was fine with it.

Cheers,
Quentin