Re: [docs] [PATCH] documentation/README: refer to doc package requirements

[Quentin Schulz <quentin.schulz@cherry.de>]

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