Bitbake's manual only refers to DocBook versions

Bitbake's manual only refers to DocBook versions

[Michael Opdenacker]

Greetings,

If you look at https://docs.yoctoproject.org/bitbake/releases.html, only
DocBook manuals are mentioned (for example
https://docs.yoctoproject.org/3.1.2/bitbake-user-manual/bitbake-user-manual.html),
but not the newer Sphinx versions. For example
https://docs.yoctoproject.org/3.1.12/bitbake-user-manual/bitbake-user-manual.html
doesn't exist.

Fortunately, at least the latest Sphinx build is available on
https://docs.yoctoproject.org/bitbake!

What about modifying this page to refer only to BitBake versions (1.48,
1.50, 1.52... plus past ones), which are the only ones that we generate,
instead of Yocto Project ones? It would then make sense to update the
switchers.js file to make it specific to BitBake.

I'm asking your opinion before proposing such a change.
Thanks in advance
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] Bitbake's manual only refers to DocBook versions

[Quentin Schulz]

Hi Michael,

On Wed, Dec 01, 2021 at 04:13:22PM +0100, Michael Opdenacker wrote:
> Greetings,
> 
> If you look at https://urldefense.proofpoint.com/v2/url?u=https-3A__docs.yoctoproject.org_bitbake_releases.html&d=DwICaQ&c=_sEr5x9kUWhuk4_nFwjJtA&r=LYjLexDn7rXIzVmkNPvw5ymA1XTSqHGq8yBP6m6qZZ4njZguQhZhkI_-172IIy1t&m=nmz6nRfD45I3bnlvaIJlwgW4wYK5G9nb3gDSkyP74fFUUHF4WlbuD9BkNH-9erYP&s=e4XFpr767d7wz5ZNyrurX3eZsxr37oW4HaNlqf6EHzc&e= , only
> DocBook manuals are mentioned (for example
> https://urldefense.proofpoint.com/v2/url?u=https-3A__docs.yoctoproject.org_3.1.2_bitbake-2Duser-2Dmanual_bitbake-2Duser-2Dmanual.html&d=DwICaQ&c=_sEr5x9kUWhuk4_nFwjJtA&r=LYjLexDn7rXIzVmkNPvw5ymA1XTSqHGq8yBP6m6qZZ4njZguQhZhkI_-172IIy1t&m=nmz6nRfD45I3bnlvaIJlwgW4wYK5G9nb3gDSkyP74fFUUHF4WlbuD9BkNH-9erYP&s=DnCrJ1SUcsVGumwq8jNF_a5K7LQiyjorQZ0QMzdSwJc&e= ),
> but not the newer Sphinx versions. For example
> https://urldefense.proofpoint.com/v2/url?u=https-3A__docs.yoctoproject.org_3.1.12_bitbake-2Duser-2Dmanual_bitbake-2Duser-2Dmanual.html&d=DwICaQ&c=_sEr5x9kUWhuk4_nFwjJtA&r=LYjLexDn7rXIzVmkNPvw5ymA1XTSqHGq8yBP6m6qZZ4njZguQhZhkI_-172IIy1t&m=nmz6nRfD45I3bnlvaIJlwgW4wYK5G9nb3gDSkyP74fFUUHF4WlbuD9BkNH-9erYP&s=ncFosfETX9y5ER-IFzjYY2xcN_XsygOFxo-MmpwA9V4&e= 
> doesn't exist.
> 

We still need to point to the older docs before Sphinx migration but
indeed it's missing the Sphinx ones.

> Fortunately, at least the latest Sphinx build is available on
> https://urldefense.proofpoint.com/v2/url?u=https-3A__docs.yoctoproject.org_bitbake-21&d=DwICaQ&c=_sEr5x9kUWhuk4_nFwjJtA&r=LYjLexDn7rXIzVmkNPvw5ymA1XTSqHGq8yBP6m6qZZ4njZguQhZhkI_-172IIy1t&m=nmz6nRfD45I3bnlvaIJlwgW4wYK5G9nb3gDSkyP74fFUUHF4WlbuD9BkNH-9erYP&s=WHxtpElE6Ddm7XaOtkShZ44Z_SAtEAADW8Nwui2veRg&e= 
> 
> What about modifying this page to refer only to BitBake versions (1.48,
> 1.50, 1.52... plus past ones), which are the only ones that we generate,
> instead of Yocto Project ones? It would then make sense to update the
> switchers.js file to make it specific to BitBake.
> 

Not sure to understand the first question, but in any case yes, we
should point to bitbake versions on this page, both pre-Sphinx and
Sphinx. However, I think we need to keep in the text in which Yocto
Project version this version of bitbake is used to make it explicit and
easy to find the bitbake doc that is important.

Not sure how this would help with switchers.js. We could always have a
check on the base URL in switchers.js. If it starts with
https://docs.yoctoproject.org/bitbake then the dropdown menu should show
Bitbake versions, otherwise YP's.

Slightly off-topic but I think we should also modify
https://git.yoctoproject.org/yocto-docs/tree/documentation/conf.py#n93
to point to the objects.inv of the bitbake version that is used by that
release. The point being that old variables may disappear over time,
breaking older YP releases docs build, which is bad. Also, it links to
the newer bitbake docs instead of the one for the one related to the YP
version the user is looking at.

Cheers,
Quentin