| Message ID | 20220321174455.1189669-1-richard.purdie@linuxfoundation.org |
|---|---|
| Headers | show |
| Series | Proposed docs version changes | expand |
On Mon, Mar 21, 2022 at 6:45 PM Richard Purdie < richard.purdie@linuxfoundation.org> wrote: > I've tweaked my patchset with some review feedback from Quentin. The v2: > > * uses yaml to load the variables in conf.py > * fixes a bitbake_mapping[i] -> branch > * fixes a comment typo in set_versions.py > * comments the bitbake langdale version mapping > > Richard Purdie (5): > Makefile/set_versions: Allow poky.yaml to be autogenerated > conf.py/set_versions/poky.yaml: Set version in conf.py from poky.yaml > set_versions: Add support for setting POKYVERSION found in older > releases > set_versions/switchers.js: Allow switchers.js version information to > be autogenerated > set_versions: Various improvements > > documentation/.gitignore | 2 + > documentation/Makefile | 1 + > documentation/conf.py | 22 +- > documentation/{poky.yaml => poky.yaml.in} | 2 + > documentation/set_versions.py | 225 ++++++++++++++++++ > Would it make sense to implement what you have in set_versions.py directly in Sphinx 'native' code ? e.g. directly in conf.py, or in a module loaded from conf.py (see how kernel does it at [1]) or yocto-vars extension, or as its own Sphinx extension? poky.yaml only purpose is to be loaded by yocto-vars.py which is a local Sphinx extension we created. [1] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/conf.py#n26 > .../{switchers.js => switchers.js.in} | 8 +- > 6 files changed, 251 insertions(+), 9 deletions(-) > rename documentation/{poky.yaml => poky.yaml.in} (98%) > create mode 100755 documentation/set_versions.py > rename documentation/sphinx-static/{switchers.js => switchers.js.in} > (97%) > > -- > 2.32.0 > > > -=-=-=-=-=-=-=-=-=-=-=- > Links: You receive all messages sent to this group. > View/Reply Online (#2663): > https://lists.yoctoproject.org/g/docs/message/2663 > Mute This Topic: https://lists.yoctoproject.org/mt/89934133/1279857 > Group Owner: docs+owner@lists.yoctoproject.org > Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [ > nicolas.dechesne@linaro.org] > -=-=-=-=-=-=-=-=-=-=-=- > >
Hi all, On 3/21/22 23:06, Richard Purdie wrote: > On Mon, 2022-03-21 at 22:56 +0100, Nicolas Dechesne wrote: >> >> >> On Mon, Mar 21, 2022 at 6:45 PM Richard Purdie >> <richard.purdie@linuxfoundation.org> wrote: >>> I've tweaked my patchset with some review feedback from Quentin. The v2: >>> >>> * uses yaml to load the variables in conf.py >>> * fixes a bitbake_mapping[i] -> branch >>> * fixes a comment typo in set_versions.py >>> * comments the bitbake langdale version mapping >>> >>> Richard Purdie (5): >>> Makefile/set_versions: Allow poky.yaml to be autogenerated >>> conf.py/set_versions/poky.yaml: Set version in conf.py from poky.yaml >>> set_versions: Add support for setting POKYVERSION found in older >>> releases >>> set_versions/switchers.js: Allow switchers.js version information to >>> be autogenerated >>> set_versions: Various improvements >>> >>> documentation/.gitignore | 2 + >>> documentation/Makefile | 1 + >>> documentation/conf.py | 22 +- >>> documentation/{poky.yaml => poky.yaml.in} | 2 + >>> documentation/set_versions.py | 225 ++++++++++++++++++ >>> >> >> >> Would it make sense to implement what you have in set_versions.py directly in >> Sphinx 'native' code ? e.g. directly in conf.py, or in a module loaded from >> conf.py (see how kernel does it at [1]) or yocto-vars extension, or as its own >> Sphinx extension? >> >> poky.yaml only purpose is to be loaded by yocto-vars.py which is a local >> Sphinx extension we created. > > Possibly, yes. I've done it like this as it was easier to validate it was doing > the right things and also easier to apply in retrospect to previous docs > releases. What we want to do going forward is an open question and it does feel > like that script would be better off as a module that at least for master, the > docs code called into. > > I think that would make most sense as a follow on to this series if/as/when > people have the time to work on it and test it accordingly. As it stands the > series was already quite painful to develop (I got hooked on Friday and had to > fix it on Saturday whilst I still had the pieces all in cache). > Agreed. I don't think this patch series makes the doc building situation worse than it currently is so there's no reason to hold it off. Makes it even easier on stable release maintainers so it's good :) I just would like the behavior to be unchanged wrt versions listed in the switchers.js, the rest is fine and can be modified later on. Which versions are listed in switchers.js can be modified in a separate commit to start the discussion (or at least have a "note" somewhere to explain what are the expectations). Cheers, Quentin
On Tue, 2022-03-22 at 14:58 +0100, Quentin Schulz wrote: > Hi all, > > On 3/21/22 23:06, Richard Purdie wrote: > > On Mon, 2022-03-21 at 22:56 +0100, Nicolas Dechesne wrote: > > > > > > Would it make sense to implement what you have in set_versions.py directly in > > > Sphinx 'native' code ? e.g. directly in conf.py, or in a module loaded from > > > conf.py (see how kernel does it at [1]) or yocto-vars extension, or as its own > > > Sphinx extension? > > > > > > poky.yaml only purpose is to be loaded by yocto-vars.py which is a local > > > Sphinx extension we created. > > > Possibly, yes. I've done it like this as it was easier to validate it > was doing > > the right things and also easier to apply in retrospect to previous docs > > releases. What we want to do going forward is an open question and it does feel > > like that script would be better off as a module that at least for master, the > > docs code called into. > > > > I think that would make most sense as a follow on to this series if/as/when > > people have the time to work on it and test it accordingly. As it stands the > > series was already quite painful to develop (I got hooked on Friday and had to > > fix it on Saturday whilst I still had the pieces all in cache). > > > > Agreed. I don't think this patch series makes the doc building situation > worse than it currently is so there's no reason to hold it off. Makes it > even easier on stable release maintainers so it's good :) > > I just would like the behavior to be unchanged wrt versions listed in > the switchers.js, the rest is fine and can be modified later on. Just to be clear, you mean adding gatesgarth and zeus back? Or adding the current version and the current version series? I'm going to assume we're talking about the first and I'll redo things to try and do that. I've decided I'd better retest everything having done that with the side be side comparison so it may take a while :/. Cheers, Richard
On 3/22/22 15:25, Richard Purdie wrote: > On Tue, 2022-03-22 at 14:58 +0100, Quentin Schulz wrote: >> Hi all, >> >> On 3/21/22 23:06, Richard Purdie wrote: >>> On Mon, 2022-03-21 at 22:56 +0100, Nicolas Dechesne wrote: >>>> >>>> Would it make sense to implement what you have in set_versions.py directly in >>>> Sphinx 'native' code ? e.g. directly in conf.py, or in a module loaded from >>>> conf.py (see how kernel does it at [1]) or yocto-vars extension, or as its own >>>> Sphinx extension? >>>> >>>> poky.yaml only purpose is to be loaded by yocto-vars.py which is a local >>>> Sphinx extension we created. >>> > Possibly, yes. I've done it like this as it was easier to validate it >> was doing >>> the right things and also easier to apply in retrospect to previous docs >>> releases. What we want to do going forward is an open question and it does feel >>> like that script would be better off as a module that at least for master, the >>> docs code called into. >>> >>> I think that would make most sense as a follow on to this series if/as/when >>> people have the time to work on it and test it accordingly. As it stands the >>> series was already quite painful to develop (I got hooked on Friday and had to >>> fix it on Saturday whilst I still had the pieces all in cache). >>> >> >> Agreed. I don't think this patch series makes the doc building situation >> worse than it currently is so there's no reason to hold it off. Makes it >> even easier on stable release maintainers so it's good :) >> >> I just would like the behavior to be unchanged wrt versions listed in >> the switchers.js, the rest is fine and can be modified later on. > > Just to be clear, you mean adding gatesgarth and zeus back? Keeping the current behavior which is the latest dot version of all releases up to Warrior. dev 3.4.2 3.3.5 3.2.4 3.1.14 3.0.4 2.7.4 is what I currently have. Quentin
On 3/22/22 15:54, Richard Purdie wrote: > On Tue, 2022-03-22 at 15:33 +0100, Quentin Schulz wrote: >> On 3/22/22 15:25, Richard Purdie wrote: >>> On Tue, 2022-03-22 at 14:58 +0100, Quentin Schulz wrote: >>>> Hi all, >>>> >>>> On 3/21/22 23:06, Richard Purdie wrote: >>>>> On Mon, 2022-03-21 at 22:56 +0100, Nicolas Dechesne wrote: >>>>>> >>>>>> Would it make sense to implement what you have in set_versions.py directly in >>>>>> Sphinx 'native' code ? e.g. directly in conf.py, or in a module loaded from >>>>>> conf.py (see how kernel does it at [1]) or yocto-vars extension, or as its own >>>>>> Sphinx extension? >>>>>> >>>>>> poky.yaml only purpose is to be loaded by yocto-vars.py which is a local >>>>>> Sphinx extension we created. >>>>> > Possibly, yes. I've done it like this as it was easier to validate it >>>> was doing >>>>> the right things and also easier to apply in retrospect to previous docs >>>>> releases. What we want to do going forward is an open question and it does feel >>>>> like that script would be better off as a module that at least for master, the >>>>> docs code called into. >>>>> >>>>> I think that would make most sense as a follow on to this series if/as/when >>>>> people have the time to work on it and test it accordingly. As it stands the >>>>> series was already quite painful to develop (I got hooked on Friday and had to >>>>> fix it on Saturday whilst I still had the pieces all in cache). >>>>> >>>> >>>> Agreed. I don't think this patch series makes the doc building situation >>>> worse than it currently is so there's no reason to hold it off. Makes it >>>> even easier on stable release maintainers so it's good :) >>>> >>>> I just would like the behavior to be unchanged wrt versions listed in >>>> the switchers.js, the rest is fine and can be modified later on. >>> >>> Just to be clear, you mean adding gatesgarth and zeus back? >> >> Keeping the current behavior which is the latest dot version of all >> releases up to Warrior. >> >> dev >> 3.4.2 >> 3.3.5 >> 3.2.4 >> 3.1.14 >> 3.0.4 >> 2.7.4 >> >> is what I currently have. > > Sadly I can't make this work easily since there are no tags for 2.7.2, 2.7.3 > ,2.7.4, 3.0.2, 3.0.3 or 3.0.4. There are a bunch of older releases missing > too :( > Quite unfortunate... We could have 3.0.4 and 2.7.4 hardcoded in switchers.js and use git tags for the rest? Quentin
These tags are in place. I back-dated them to the release day but I put them in my name since I've added these without a release engineer involved. On Tue, Mar 22, 2022 at 8:00 AM Richard Purdie < richard.purdie@linuxfoundation.org> wrote: > On Tue, 2022-03-22 at 14:54 +0000, Richard Purdie via > lists.yoctoproject.org > wrote: > > On Tue, 2022-03-22 at 15:33 +0100, Quentin Schulz wrote: > > > On 3/22/22 15:25, Richard Purdie wrote: > > > > On Tue, 2022-03-22 at 14:58 +0100, Quentin Schulz wrote: > > > > > Hi all, > > > > > > > > > > On 3/21/22 23:06, Richard Purdie wrote: > > > > > > On Mon, 2022-03-21 at 22:56 +0100, Nicolas Dechesne wrote: > > > > > > > > > > > > > > Would it make sense to implement what you have in > set_versions.py directly in > > > > > > > Sphinx 'native' code ? e.g. directly in conf.py, or in a > module loaded from > > > > > > > conf.py (see how kernel does it at [1]) or yocto-vars > extension, or as its own > > > > > > > Sphinx extension? > > > > > > > > > > > > > > poky.yaml only purpose is to be loaded by yocto-vars.py which > is a local > > > > > > > Sphinx extension we created. > > > > > > > Possibly, yes. I've done it like this as it was easier to > validate it > > > > > was doing > > > > > > the right things and also easier to apply in retrospect to > previous docs > > > > > > releases. What we want to do going forward is an open question > and it does feel > > > > > > like that script would be better off as a module that at least > for master, the > > > > > > docs code called into. > > > > > > > > > > > > I think that would make most sense as a follow on to this series > if/as/when > > > > > > people have the time to work on it and test it accordingly. As > it stands the > > > > > > series was already quite painful to develop (I got hooked on > Friday and had to > > > > > > fix it on Saturday whilst I still had the pieces all in cache). > > > > > > > > > > > > > > > > Agreed. I don't think this patch series makes the doc building > situation > > > > > worse than it currently is so there's no reason to hold it off. > Makes it > > > > > even easier on stable release maintainers so it's good :) > > > > > > > > > > I just would like the behavior to be unchanged wrt versions listed > in > > > > > the switchers.js, the rest is fine and can be modified later on. > > > > > > > > Just to be clear, you mean adding gatesgarth and zeus back? > > > > > > Keeping the current behavior which is the latest dot version of all > > > releases up to Warrior. > > > > > > dev > > > 3.4.2 > > > 3.3.5 > > > 3.2.4 > > > 3.1.14 > > > 3.0.4 > > > 2.7.4 > > > > > > is what I currently have. > > > > Sadly I can't make this work easily since there are no tags for 2.7.2, > 2.7.3 > > ,2.7.4, 3.0.2, 3.0.3 or 3.0.4. There are a bunch of older releases > missing > > too :( > > Michael(H), would you be able to add some tags: > > yocto-2.7.4 3fd1432890f04fd659952c0f20f5750fb8c3a909 > yocto-2.7.3 a06e6bdf1d8f133dfaf6dad9c49be24f688799c4 > yocto-2.7.2 ee29f61b92c5ca7dd56393cef5fcd3ff3fe243aa > yocto-3.0.2 ac75b463b23ae6258c1e6f3bbdefc398f3a03d43 > yocto-3.0.3 9d522e747d2715aa0b2fe4c81cacc34bfad3e1a3 > yocto-3.0.4 9f51be3a11b7422aba3617a90a98336c3c75f71e > > please? > > Cheers, > > Richard > >
On Tue, 2022-03-22 at 17:47 -0700, Michael Halstead wrote: > These tags are in place. I back-dated them to the release day but I put them > in my name since I've added these without a release engineer involved. > > > > Thanks, this helps immensely! Cheers, Richard
I've tweaked my patchset with some review feedback from Quentin. The v2: * uses yaml to load the variables in conf.py * fixes a bitbake_mapping[i] -> branch * fixes a comment typo in set_versions.py * comments the bitbake langdale version mapping Richard Purdie (5): Makefile/set_versions: Allow poky.yaml to be autogenerated conf.py/set_versions/poky.yaml: Set version in conf.py from poky.yaml set_versions: Add support for setting POKYVERSION found in older releases set_versions/switchers.js: Allow switchers.js version information to be autogenerated set_versions: Various improvements documentation/.gitignore | 2 + documentation/Makefile | 1 + documentation/conf.py | 22 +- documentation/{poky.yaml => poky.yaml.in} | 2 + documentation/set_versions.py | 225 ++++++++++++++++++ .../{switchers.js => switchers.js.in} | 8 +- 6 files changed, 251 insertions(+), 9 deletions(-) rename documentation/{poky.yaml => poky.yaml.in} (98%) create mode 100755 documentation/set_versions.py rename documentation/sphinx-static/{switchers.js => switchers.js.in} (97%)