| Message ID | 20240611125026.22702-1-michael@opdenacker.org |
|---|---|
| State | New |
| Headers | show |
| Series | documentation/README: refer to doc package requirements | expand |
Hi Michael, On 6/11/24 2:50 PM, Michael Opdenacker via lists.yoctoproject.org wrote: > From: Michael Opdenacker <michael@opdenacker.org> > > 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 <michael@opdenacker.org> > --- > documentation/README | 29 +++-------------------------- > 1 file changed, 3 insertions(+), 26 deletions(-) > > diff --git a/documentation/README b/documentation/README > index b60472fcbf..c888b666a8 100644 > --- a/documentation/README > +++ b/documentation/README > @@ -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 > 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 Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de> Thanks! Quentin
Hi Quentin, Thanks for the review! On 6/13/24 10:37, Quentin Schulz via lists.yoctoproject.org wrote: > Hi Michael, > > On 6/11/24 2:50 PM, Michael Opdenacker via lists.yoctoproject.org wrote: >> From: Michael Opdenacker <michael@opdenacker.org> >> >> 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 <michael@opdenacker.org> >> --- >> documentation/README | 29 +++-------------------------- >> 1 file changed, 3 insertions(+), 26 deletions(-) >> >> diff --git a/documentation/README b/documentation/README >> index b60472fcbf..c888b666a8 100644 >> --- a/documentation/README >> +++ b/documentation/README >> @@ -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 >> > > 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.
Hi Michael, On 6/18/24 4:52 PM, Michael Opdenacker via lists.yoctoproject.org wrote: > Hi Quentin, > > Thanks for the review! > > On 6/13/24 10:37, Quentin Schulz via lists.yoctoproject.org wrote: >> Hi Michael, >> >> On 6/11/24 2:50 PM, Michael Opdenacker via lists.yoctoproject.org wrote: >>> From: Michael Opdenacker <michael@opdenacker.org> >>> >>> 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 <michael@opdenacker.org> >>> --- >>> documentation/README | 29 +++-------------------------- >>> 1 file changed, 3 insertions(+), 26 deletions(-) >>> >>> diff --git a/documentation/README b/documentation/README >>> index b60472fcbf..c888b666a8 100644 >>> --- a/documentation/README >>> +++ b/documentation/README >>> @@ -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 >> >> 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. > 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
diff --git a/documentation/README b/documentation/README index b60472fcbf..c888b666a8 100644 --- a/documentation/README +++ b/documentation/README @@ -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: