documentation/README: refer to doc package requirements
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
@@ -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:
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.
Signed-off-by Michael Opdenacker <[email protected]>--- documentation/README | 29 +++-------------------------- 1 file changed, 3 insertions(+), 26 deletions(-)documentation/README +0
-20@@ -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
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.
Signed-off-by Michael Opdenacker <[email protected]>---
documentation/README | 29 +++--------------------------1 file changed, 3 insertions(+), 26 deletions(-)documentation/README +0
-0@@ -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, fordocumentation/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 buildPDFs. 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 areThis 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.rstandPIP3_HOST_PACKAGESin 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.
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.
Signed-off-by Michael Opdenacker <[email protected]>---
documentation/README | 29 +++--------------------------1 file changed, 3 insertions(+), 26 deletions(-)documentation/README +0
-0@@ -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, fordocumentation/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 buildPDFs. Debian
-and Ubuntu have it in "texlive-latex-extra" package while RedHatQuoted 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 areThis 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.rstandPIP3_HOST_PACKAGESin 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