Re: [docs] [PATCH RFC 2/2] tools: add script for building documentation inside containers

["Antonin Godard" <antonin.godard@bootlin.com>]

Hi Quentin,

On Tue Dec 17, 2024 at 2:50 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>
>>>
>>> This adds a script for building a container and building the
>>> documentation within that new container image.
>>>
>>> The openSUSE instructions now require a --non-interactive flag otherwise
>>> they fail to run. Sadly there doesn't seem to be a way to have this in
>>> an environment variable à-la DEBIAN_FRONTEND=noninteractive.
>>>
>>> Note that the Ubuntu and openSUSE instructions currently do not work.
>>>
>>> Signed-off-by: Quentin Schulz <quentin.schulz@cherry.de>
>>> ---
>>>   documentation/tools/Containerfile.almalinux        |   1 +
>>>   documentation/tools/Containerfile.apt              |  21 +++++
>>>   documentation/tools/Containerfile.debian           |   1 +
>>>   documentation/tools/Containerfile.dnf              |  19 ++++
>>>   documentation/tools/Containerfile.fedora           |   1 +
>>>   documentation/tools/Containerfile.ubuntu           |   1 +
>>>   documentation/tools/Containerfile.zypper           |  18 ++++
>>>   documentation/tools/build-docs-container           | 101 +++++++++++++++++++++
>>>   documentation/tools/opensuse_host_packages_docs.sh |   2 +-
>>>   .../tools/opensuse_host_packages_essential.sh      |   2 +-
>>>   10 files changed, 165 insertions(+), 2 deletions(-)
>>>
>>> diff --git a/documentation/tools/Containerfile.almalinux b/documentation/tools/Containerfile.almalinux
>>> new file mode 120000
>>> index 0000000000000000000000000000000000000000..7237e9b99f4132957c0ad5b11fa6cefe9daaec74
>>> --- /dev/null
>>> +++ b/documentation/tools/Containerfile.almalinux
>>> @@ -0,0 +1 @@
>>> +Containerfile.dnf
>>> \ No newline at end of file
>>> diff --git a/documentation/tools/Containerfile.apt b/documentation/tools/Containerfile.apt
>>> new file mode 100644
>>> index 0000000000000000000000000000000000000000..a601699ce4005b3bc5288990dbf2e7fa235ea431
>>> --- /dev/null
>>> +++ b/documentation/tools/Containerfile.apt
>>> @@ -0,0 +1,21 @@
>>> +ARG ARG_FROM=debian:12 # default value to avoid warning
>>> +FROM $ARG_FROM
>>> +
>>> +ARG HOST_DOCS_PACKAGES=ubuntu_host_packages_docs.sh
>>> +
>>> +ENV DEBIAN_FRONTEND=noninteractive
>>> +
>>> +# relative to the location of the dockerfile
>>> +COPY --chmod=777 ${HOST_DOCS_PACKAGES} /temp/host_packages_docs.sh
>>> +
>>> +RUN apt-get update \
>>> + && apt-get install -y sudo \
>>> + && yes | /temp/host_packages_docs.sh \
>>> + && apt-get --yes autoremove \
>>> + && apt-get clean \
>>> + && rm -rf /temp
>>> +
>>> +RUN git config --global --add safe.directory /docs
>>> +
>>> +ENTRYPOINT ["/usr/bin/env", "make", "-C", "documentation/"]
>>> +CMD ["publish"]
>> 
>> Are we able to override this from the command-line, with the
>> build-docs-container script? I assume everything passed in "$*" below replaces
>> CMD?
>> 
>
> Yes, I'm currently calling the script like that:
>
> ./tools/build-docs-container fedora:40 html
> ./tools/build-docs-container fedora:40 latexpdf
>
> or ./tools/build-docs-container fedora:40 latexpdf html (in v2, broken 
> in v1).
>
> If you omit it, it'll call "publish", which is what you decided would be 
> the default in **your** v1. We can have nothing instead which would call 
> "all" I guess instead? Up to you.

"publish" is similar to all, but goes a bit further to assemble the documents
and gives a better representation of the final state of the docs IMO (how they're
actually published). I think the main advantage is the "final" directory in
the build dir, which gathers everything in one place.

TLDR: the extra cost of running publish instead of all is low, we might as well
just run it by default :)

Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com