[PATCH yocto-autobuilder-helper] scripts/run-docs-build: make all versions list releases known to master

[PATCH yocto-autobuilder-helper] scripts/run-docs-build: make all versions list releases known to master

[Michael Opdenacker]

This allows all versions of Bitbake and Yocto Project manuals
to see the manuals for the latest versions.

This also simplifies the release process, not having to update the
releases.rst file for all releases every time a new release is made.

Note that such synchronization is already done for the
switchers.js file (but in a different way). This way, advertised
releases are in sync with switchers.js.

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 scripts/run-docs-build | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/scripts/run-docs-build b/scripts/run-docs-build
index 4451018..5d6d24a 100755
--- a/scripts/run-docs-build
+++ b/scripts/run-docs-build
@@ -39,8 +39,11 @@ cp -r ./_build/final/* $outputdir/bitbake/next
 # A decision was made to keep updating all the Sphinx generated docs for the moment,
 # even the ones corresponding to no longer supported releases
 # https://lists.yoctoproject.org/g/docs/message/2193
+# We copy the releases.rst file from master so that all versions of the docs
+# see the latest releases.
 for branch in 1.46 1.48 1.50 1.52; do
     git checkout $branch
+    git checkout master doc/releases.rst
     make clean
     make publish
     mkdir $outputdir/bitbake/$branch
@@ -76,6 +79,7 @@ cp -r ./_build/final/* $outputdir/next
 for branch in dunfell gatesgarth hardknott honister; do
     cd $ypdocs
     git checkout $branch
+    git checkout master documentation/releases.rst
     make clean
     make publish
     mkdir $outputdir/$branch
@@ -97,6 +101,7 @@ for tag in $(git tag --list 'yocto-*'); do
         if [ "$tag" = "yocto-3.3" ] || [ "$tag" = "yocto-3.4" ]; then
             git am "${scriptdir}/${tag}/0001-conf-update-for-release.patch"
         fi
+        git checkout master documentation/releases.rst
         make clean
         make publish
         version=$(echo $tag | cut -c7-)
-- 
2.25.1

Re: [docs] [PATCH yocto-autobuilder-helper] scripts/run-docs-build: make all versions list releases known to master

[Quentin Schulz]

Hi Michael,

On Wed, Dec 01, 2021 at 02:49:31PM +0100, Michael Opdenacker wrote:
> This allows all versions of Bitbake and Yocto Project manuals
> to see the manuals for the latest versions.
> 
> This also simplifies the release process, not having to update the
> releases.rst file for all releases every time a new release is made.
> 
> Note that such synchronization is already done for the
> switchers.js file (but in a different way). This way, advertised
> releases are in sync with switchers.js.
> 

Why don't we migrate this different method (find) to the one you
implement in this commit too?

I could see a variable storing all "force-latest" files or someting like
that to make it obvious why they have a specific handling.

> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
> ---
>  scripts/run-docs-build | 5 +++++
>  1 file changed, 5 insertions(+)
> 
> diff --git a/scripts/run-docs-build b/scripts/run-docs-build
> index 4451018..5d6d24a 100755
> --- a/scripts/run-docs-build
> +++ b/scripts/run-docs-build
> @@ -39,8 +39,11 @@ cp -r ./_build/final/* $outputdir/bitbake/next
>  # A decision was made to keep updating all the Sphinx generated docs for the moment,
>  # even the ones corresponding to no longer supported releases
>  # https://urldefense.proofpoint.com/v2/url?u=https-3A__lists.yoctoproject.org_g_docs_message_2193&d=DwIDAg&c=_sEr5x9kUWhuk4_nFwjJtA&r=LYjLexDn7rXIzVmkNPvw5ymA1XTSqHGq8yBP6m6qZZ4njZguQhZhkI_-172IIy1t&m=41QznJ3f-1jbT6A1N9c2-XE7vAUbnla1A6cM0yaU8thgWg_WVfeII9dfe8Uq2JTO&s=YCQsQAquPWLLWl11yDzvgP9zkF-UkMF0c8B3BASBDbk&e= 
> +# We copy the releases.rst file from master so that all versions of the docs
> +# see the latest releases.
>  for branch in 1.46 1.48 1.50 1.52; do
>      git checkout $branch
> +    git checkout master doc/releases.rst

That's one way to do it, not sure this is really what we want but at
least it lowers the maintenance burden so it's a good improvement.

Cheers,
Quentin

Re: [docs] [PATCH yocto-autobuilder-helper] scripts/run-docs-build: make all versions list releases known to master

[Michael Opdenacker]

Hi Quentin,

Thanks for the review and for your suggestions.

On 12/3/21 10:34 AM, Quentin Schulz wrote:
> Hi Michael,
>
> On Wed, Dec 01, 2021 at 02:49:31PM +0100, Michael Opdenacker wrote:
>> This allows all versions of Bitbake and Yocto Project manuals
>> to see the manuals for the latest versions.
>>
>> This also simplifies the release process, not having to update the
>> releases.rst file for all releases every time a new release is made.
>>
>> Note that such synchronization is already done for the
>> switchers.js file (but in a different way). This way, advertised
>> releases are in sync with switchers.js.
>>
> Why don't we migrate this different method (find) to the one you
> implement in this commit too?
>
> I could see a variable storing all "force-latest" files or someting like
> that to make it obvious why they have a specific handling.


I tried, but I stumble on the need to copy the latest switchers.js from
yocto-docs to the Bitbake branches too.

And since the Bitbake branches need to be checked out and processed
first, I hesitate to add a special extra step to checkout the yocto-docs
repo before. Possible but adding complexity.

So, if I don't use this way for the Bitbake branches, I still need a
find command at the end...

If you don't think about any better idea, I'd propose to stick to this
version of the patch.

Cheers
Michael.

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