[RFC,1/2] docs: use literalinclude for system requirements

From: Quentin Schulz <quentin.schulz@cherry.de>

The YAML variables for the host dependencies are updated by hand and
actually only used inside code blocks.

It's also slowly getting more difficult to make sense of the content of
those variables as they are both the list of packages to install with
the distro's package manager and sometimes additional commands, which
all need to have the indentation of the block where the variable is used
matched. This is impossible so we just guess it's going to be at a
specific indentation.

Instead, let's migrate all instructions into separate shell scripts that
are then literalinclude'd into the Sphinx documentation.

This allows a few things:
- ability to run shellcheck on the scripts if we ever want to
- manually calling the appropriate script from a supported distro to
  build stuff (distro or bitbake/yocto stuff)
- use this script to create containers to do CI of documentation on
  different distros, to make sure our instructions are all up to date,

Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
---
 documentation/poky.yaml.in                         | 26 -------------
 documentation/ref-manual/system-requirements.rst   | 45 ++++++++++++----------
 .../tools/almalinux_host_packages_docs.sh          |  2 +
 .../tools/almalinux_host_packages_essential.sh     |  5 +++
 documentation/tools/fedora_host_packages_docs.sh   |  2 +
 .../tools/fedora_host_packages_essential.sh        |  1 +
 documentation/tools/opensuse_host_packages_docs.sh |  2 +
 .../tools/opensuse_host_packages_essential.sh      |  2 +
 documentation/tools/ubuntu_host_packages_docs.sh   |  2 +
 .../tools/ubuntu_host_packages_essential.sh        |  2 +
 10 files changed, 42 insertions(+), 47 deletions(-)

Hi Quentin,

On Tue Dec 10, 2024 at 4:26 PM CET, Quentin Schulz wrote:
> From: Quentin Schulz <quentin.schulz@cherry.de>
>
> The YAML variables for the host dependencies are updated by hand and
> actually only used inside code blocks.
>
> It's also slowly getting more difficult to make sense of the content of
> those variables as they are both the list of packages to install with
> the distro's package manager and sometimes additional commands, which
> all need to have the indentation of the block where the variable is used
> matched. This is impossible so we just guess it's going to be at a
> specific indentation.
>
> Instead, let's migrate all instructions into separate shell scripts that
> are then literalinclude'd into the Sphinx documentation.
>
> This allows a few things:
> - ability to run shellcheck on the scripts if we ever want to
> - manually calling the appropriate script from a supported distro to
>   build stuff (distro or bitbake/yocto stuff)
> - use this script to create containers to do CI of documentation on
>   different distros, to make sure our instructions are all up to date,
>
> Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
> ---
>  documentation/poky.yaml.in                         | 26 -------------
>  documentation/ref-manual/system-requirements.rst   | 45 ++++++++++++----------
>  .../tools/almalinux_host_packages_docs.sh          |  2 +

Maybe I would put the scripts in a subdirectory called "host_packages_scripts"
and rename the scripts "almalinux_docs.sh", "almalinux_essential.sh", etc. for
shorter names. Same for Containerfiles in the next patch, maybe storing them in
a subdirectory would make sense.

If putting them at the same level is because of the build context requiring
files to be all at the same place, let's leave it like this.


Otherwise, this needs to be rebased and updated after the dependencies were
updated on master.

Thanks,
Antonin

Hi Antonin,

On 12/17/24 11:31 AM, Antonin Godard wrote:
> Hi Quentin,
> 
> On Tue Dec 10, 2024 at 4:26 PM CET, Quentin Schulz wrote:
>> From: Quentin Schulz <quentin.schulz@cherry.de>
>>
>> The YAML variables for the host dependencies are updated by hand and
>> actually only used inside code blocks.
>>
>> It's also slowly getting more difficult to make sense of the content of
>> those variables as they are both the list of packages to install with
>> the distro's package manager and sometimes additional commands, which
>> all need to have the indentation of the block where the variable is used
>> matched. This is impossible so we just guess it's going to be at a
>> specific indentation.
>>
>> Instead, let's migrate all instructions into separate shell scripts that
>> are then literalinclude'd into the Sphinx documentation.
>>
>> This allows a few things:
>> - ability to run shellcheck on the scripts if we ever want to
>> - manually calling the appropriate script from a supported distro to
>>    build stuff (distro or bitbake/yocto stuff)
>> - use this script to create containers to do CI of documentation on
>>    different distros, to make sure our instructions are all up to date,
>>
>> Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
>> ---
>>   documentation/poky.yaml.in                         | 26 -------------
>>   documentation/ref-manual/system-requirements.rst   | 45 ++++++++++++----------
>>   .../tools/almalinux_host_packages_docs.sh          |  2 +
> 
> Maybe I would put the scripts in a subdirectory called "host_packages_scripts"
> and rename the scripts "almalinux_docs.sh", "almalinux_essential.sh", etc. for
> shorter names. Same for Containerfiles in the next patch, maybe storing them in
> a subdirectory would make sense.
> 
> If putting them at the same level is because of the build context requiring
> files to be all at the same place, let's leave it like this.
> 

Will check for a v3 but should be doable I believe.

> 
> Otherwise, this needs to be rebased and updated after the dependencies were
> updated on master.
> 

That's already done in the v2 I sent yesterday :)

Cheers,
Quentin

Hi Quentin,

On Tue Dec 17, 2024 at 1:58 PM CET, Quentin Schulz wrote:
> Hi Antonin,
>
> On 12/17/24 11:31 AM, Antonin Godard wrote:
>> Hi Quentin,
>> 
>> On Tue Dec 10, 2024 at 4:26 PM CET, Quentin Schulz wrote:
>>> From: Quentin Schulz <quentin.schulz@cherry.de>
>>>
>>> The YAML variables for the host dependencies are updated by hand and
>>> actually only used inside code blocks.
>>>
>>> It's also slowly getting more difficult to make sense of the content of
>>> those variables as they are both the list of packages to install with
>>> the distro's package manager and sometimes additional commands, which
>>> all need to have the indentation of the block where the variable is used
>>> matched. This is impossible so we just guess it's going to be at a
>>> specific indentation.
>>>
>>> Instead, let's migrate all instructions into separate shell scripts that
>>> are then literalinclude'd into the Sphinx documentation.
>>>
>>> This allows a few things:
>>> - ability to run shellcheck on the scripts if we ever want to
>>> - manually calling the appropriate script from a supported distro to
>>>    build stuff (distro or bitbake/yocto stuff)
>>> - use this script to create containers to do CI of documentation on
>>>    different distros, to make sure our instructions are all up to date,
>>>
>>> Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
>>> ---
>>>   documentation/poky.yaml.in                         | 26 -------------
>>>   documentation/ref-manual/system-requirements.rst   | 45 ++++++++++++----------
>>>   .../tools/almalinux_host_packages_docs.sh          |  2 +
>> 
>> Maybe I would put the scripts in a subdirectory called "host_packages_scripts"
>> and rename the scripts "almalinux_docs.sh", "almalinux_essential.sh", etc. for
>> shorter names. Same for Containerfiles in the next patch, maybe storing them in
>> a subdirectory would make sense.
>> 
>> If putting them at the same level is because of the build context requiring
>> files to be all at the same place, let's leave it like this.
>> 
>
> Will check for a v3 but should be doable I believe.
>
>> 
>> Otherwise, this needs to be rebased and updated after the dependencies were
>> updated on master.
>> 
>
> That's already done in the v2 I sent yesterday :)

Strange, I did not receive it, and I can't find it on
lore.kernel.org/yocto-docs. Is the issue on my side?

Antonin

Hi Antonin,

On 12/17/24 2:10 PM, Antonin Godard wrote:
> Hi Quentin,
> 
> On Tue Dec 17, 2024 at 1:58 PM CET, Quentin Schulz wrote:
>> Hi Antonin,
>>
>> On 12/17/24 11:31 AM, Antonin Godard wrote:
>>> Hi Quentin,
>>>
>>> On Tue Dec 10, 2024 at 4:26 PM CET, Quentin Schulz wrote:
>>>> From: Quentin Schulz <quentin.schulz@cherry.de>
>>>>
>>>> The YAML variables for the host dependencies are updated by hand and
>>>> actually only used inside code blocks.
>>>>
>>>> It's also slowly getting more difficult to make sense of the content of
>>>> those variables as they are both the list of packages to install with
>>>> the distro's package manager and sometimes additional commands, which
>>>> all need to have the indentation of the block where the variable is used
>>>> matched. This is impossible so we just guess it's going to be at a
>>>> specific indentation.
>>>>
>>>> Instead, let's migrate all instructions into separate shell scripts that
>>>> are then literalinclude'd into the Sphinx documentation.
>>>>
>>>> This allows a few things:
>>>> - ability to run shellcheck on the scripts if we ever want to
>>>> - manually calling the appropriate script from a supported distro to
>>>>     build stuff (distro or bitbake/yocto stuff)
>>>> - use this script to create containers to do CI of documentation on
>>>>     different distros, to make sure our instructions are all up to date,
>>>>
>>>> Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
>>>> ---
>>>>    documentation/poky.yaml.in                         | 26 -------------
>>>>    documentation/ref-manual/system-requirements.rst   | 45 ++++++++++++----------
>>>>    .../tools/almalinux_host_packages_docs.sh          |  2 +
>>>
>>> Maybe I would put the scripts in a subdirectory called "host_packages_scripts"
>>> and rename the scripts "almalinux_docs.sh", "almalinux_essential.sh", etc. for
>>> shorter names. Same for Containerfiles in the next patch, maybe storing them in
>>> a subdirectory would make sense.
>>>
>>> If putting them at the same level is because of the build context requiring
>>> files to be all at the same place, let's leave it like this.
>>>
>>
>> Will check for a v3 but should be doable I believe.
>>
>>>
>>> Otherwise, this needs to be rebased and updated after the dependencies were
>>> updated on master.
>>>
>>
>> That's already done in the v2 I sent yesterday :)
> 
> Strange, I did not receive it, and I can't find it on
> lore.kernel.org/yocto-docs. Is the issue on my side?
> 

Typical PEBKAC, forgot to run b4 prep --auto-to-cc on the patch series 
before sending it (it warned me I hadn't run the command yet but I had 
sent the v1 already so I thought it was a spurious warning message) so I 
sent it to a whopping amount of one recipient... myself.

Will send with the requested changes as v2 once ready :) Thanks for the 
heads up.

Cheers,
Quentin