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

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

[michael]

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
 
 To build the documentation locally, run:
 

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

[Quentin Schulz]

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

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

[Michael Opdenacker]

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.

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

[Quentin Schulz]

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