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

[Michael Opdenacker <michael@opdenacker.org>]

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.