Re: [docs] [PATCH 1/2] poky.yaml: introduce DISTRO_LATEST_TAG

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

Hi Quentin,

On Fri Apr 18, 2025 at 1:28 PM CEST, Quentin Schulz wrote:
[...]
>>> I seem to recall we wanted the variables set by set_versions.py to still
>>> be able to build the docs from tarballs and not force the use of git
>>> repos? But it seems like we force to fetch git tags at the very
>>> beginning of the Python script.
>> 
>>    $ make html
>>    ./set_versions.py
>>    Please run 'git fetch --tags' before building the documentation
>>    make: *** [Makefile:72: html] Error 1
>> 
>> It is indeed a bug!
>> Created one here: https://bugzilla.yoctoproject.org/show_bug.cgi?id=15834
>> 
>>> So I'm wondering if we should only have variables that aren't replaced
>>> in poky.yaml.in and eventually have the ones set_versions.py adds in
>>> poky.yaml (instead of replacing for example) documented in comments to
>>> explain what they are and in which context(s) to use them?
>> 
>> That would be a bit cleaner yes.
>> 
>> Maybe standards.md would be a good place? i.e.:
>> "Use &DISTRO; in the docs when wanting to refer to the latest possible version"
>> "Use &DISTRO_LATEST_TAG; in the docs when wanting to refer to the latest
>> existing tag"
>> etc.
>> 
>
> If we need to restore building the docs from tarballs, then we need 
> default values (and appropriate ones!) in poky.yaml.in. We could still 
> explain proper usage in standards.md , though, up to you.

I discussed this with Richard the other day, and it was decided to not support
building the docs from tarballs in the end. As mentioned in the ticket above, I
will simply state that the docs must be built from the Git repository in a
message when trying to build from a tarball.

> I would simply split the file in two with a big comment before the 
> second section where we would define overridden variables?

Yep, re-organizing the file seems like a good approach to me too - easy and
effective.

> I don't think we should be using &DISTRO; anymore? Most of the time we 
> don't want to be printing .999 on the landing page of 
> docs.yoctoproject.org! For the dev page, that's different.

I would like to agree, but at the same time, wouldn't it be confusing to have a
real tag (e.g. 5.1.8) when reading for the latest tip of the branch? It would be
somewhat accurate, but not _stricty_ accurate as to which version of the doc you
are actually reading (the latest tip).

I'm trying to think of a way to make it clear that 999 represent the branch's
tip.

Some ideas to replace or append to the 999:

"5.1 (<short commit sha>)"
"5.1.999 (<short commit sha>)"
"5.1+<short commit sha>"
"5.1+<short commit sha>+<branch name>"

Maybe just using an output from `git describe` (modified to render what we want)
could be enough?

> Cheers,
> Quentin

Thanks,
Antonin

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