[yocto-autobuilder-helper,v8] Add a banner on the old documentation docs.

Signed-off-by: Abongwa Bonalais Amahnui <abongwabonalais@gmail.com>
---
 scripts/docs_fix_all_html_css.py | 85 ++++++++++++++++++++++++++++++++
 scripts/run-docs-build           |  1 +
 2 files changed, 86 insertions(+)
 create mode 100755 scripts/docs_fix_all_html_css.py

> +from logging import root
> +import os
> +import re

The logging and re imports are unused, remove these.

> +
> +
> +html_content = '''
> +<div id="outdated-warning">This document is outdated, you should select the <a href="https://docs.yoctoproject.org/">latest release version</a> in this series.</div>
> +<div xml:lang="en" class="body" lang="en">
> +'''
> +last_div = '''
> +</div>

Add a comment explaining why you need to add a <div> wrapping the main content.

> +    # pattern = '^3.1*'
> +    # exclude = re.search(pattern, dir)
> +def loop_through_html_directories(dir):
> +    for root, dirs, filenames in os.walk(dir, topdown=True):
> +        # loop through all files in the directory
> +        exclude = set(['3.1', '3.1.1', '3.1.2', '3.1.3'])

Hardcoding numbers like this isn’t a great idea.  If the intention is to add the warning on all versions earlier than 3.2, then the regex approach that is commented out would be better.  It most likely didn’t work as regex matching isn’t like shell/windows matching:

pattern = r”^3\.1.*"

A good solution would be to use packaging.version.parse, but that’s not a built-in module so would need to be added to the build. That can wait, the regex solution should be good.

A comment here explaining what the exclusion is for, and why 3.1, would be good.

> +        dirs[:] = list(filter(lambda x: not x in exclude, dirs))
> +        for filename in filenames:
> +            # check if the file is an html file

No need for obvious comments

> +            if filename.endswith('.html'):
> +                # open the html file in read mode

Obvious comment, again, and several times below.

Ross
IMPORTANT NOTICE: The contents of this email and any attachments are confidential and may also be privileged. If you are not the intended recipient, please notify the sender immediately and do not disclose the contents to any other person, use it for any purpose, or store or copy the information in any medium. Thank you.

Hi Ross,

On 4/25/22 10:43, Ross Burton wrote:
>> +from logging import root
>> +import os
>> +import re
> 
> The logging and re imports are unused, remove these.
> 
>> +
>> +
>> +html_content = '''
>> +<div id="outdated-warning">This document is outdated, you should select the <a href="https://urldefense.proofpoint.com/v2/url?u=https-3A__docs.yoctoproject.org_&amp;d=DwMGaQ&amp;c=_sEr5x9kUWhuk4_nFwjJtA&amp;r=LYjLexDn7rXIzVmkNPvw5ymA1XTSqHGq8yBP6m6qZZ4njZguQhZhkI_-172IIy1t&amp;m=3Ugg7DXNtg5Jzu8oqGU6VwYTbn01QrCiaWSKjVlkEVKyVfiZZnaOgnCbTgFNdaTg&amp;s=NpHhdUuDWyKDzpnNui16Z9MijVOTPcXWU2zzwvY-aWw&amp;e=">latest release version</a> in this series.</div>
>> +<div xml:lang="en" class="body" lang="en">
>> +'''
>> +last_div = '''
>> +</div>
> 
> Add a comment explaining why you need to add a <div> wrapping the main content.
> 
>> +    # pattern = '^3.1*'
>> +    # exclude = re.search(pattern, dir)
>> +def loop_through_html_directories(dir):
>> +    for root, dirs, filenames in os.walk(dir, topdown=True):
>> +        # loop through all files in the directory
>> +        exclude = set(['3.1', '3.1.1', '3.1.2', '3.1.3'])
> 
> Hardcoding numbers like this isn’t a great idea.  If the intention is to add the warning on all versions earlier than 3.2, then the regex approach that is commented out would be better.  It most likely didn’t work as regex matching isn’t like shell/windows matching:
> 
> pattern = r”^3\.1.*"
> 
> A good solution would be to use packaging.version.parse, but that’s not a built-in module so would need to be added to the build. That can wait, the regex solution should be good.
> 

To be fair, the list of impacted versions for dunfell is finite, since 
we're talking about old docs that aren't regenerated anymore. Dunfell 
was migrated to Sphinx (and is thus regenerated by run-docs-build 
script) in 3.1.5. (So I think we're missing 3.1.4 in there.)

For Dunfell, this message will ultimately be replaced with the obsolete 
message common to all other old docs, in 2 years from now, when it's 
obsolete.

Just to give more context, I'm not particularly pushing for anything here.

Cheers,
Quentin

> 
> Hardcoding numbers like this isn’t a great idea. If the intention is to
> add the warning on all versions earlier than 3.2, then the regex approach
> that is commented out would be better. It most likely didn’t work as regex
> matching isn’t like shell/windows matching: pattern = r”^3\.1.*" A good
> solution would be to use packaging.version.parse, but that’s not a
> built-in module so would need to be added to the build. That can wait, the
> regex solution should be good.
> 

Hi Ross, I tried out the regex solution but I did not work and I also noticed that the 3.1.x doc versions on the documentation website already contains the banner
I thought from 3.1.2 above were not outdate to, I am a little bit confused about which version is the latest.