[WIP] Unpin rstcheck dependency and update to version 6.x

[ganeshhubale]

• Removed the version pin(5.0.0) for rstcheck to allow updates to the latest version (6.x).
• Updated the rstcheck.py script to handle changes in the rstcheck-core API and output format.

Issue resolved: #1710

[ansible-documentation-bot]

The following files are automatically generated and should not be modified outside of the Ansible release process:

• docs/docsite/rst/porting_guides/porting_guide_2.0.rst

Please double-check your changes.

[ganeshhubale]

Hi @oraNod ,
I have addressed most of the issues and made the necessary changes to the documentation files. Could you please confirm if the changes align with the expected direction?

While I’ve resolved the majority of syntax and parsing errors, the AttributeError issue still persists. This seems to be caused by an existing bug in the rstcheck_core library. Below is the error message for reference:

An `AttributeError` error occured. This is most probably due to a code block directive (code/code-block/sourcecode) without a specified language. This may result in a false negative for source: '/home/runner/work/ansible-documentation/ansible-documentation/docs/docsite/rst/network/user_guide/platform_enos.rst'. The reason can also be another directive. For more information see the FAQ (https://rstcheck-core.rtfd.io/en/latest/faq) or the corresponding github issue: https://github.com/rstcheck/rstcheck-core/issues/3.

Would it be acceptable to ignore this issue given its root cause in the library? I appreciate your guidance on how to proceed.

[oraNod]

Hi @oraNod , I have addressed most of the issues and made the necessary changes to the documentation files. Could you please confirm if the changes align with the expected direction?

While I’ve resolved the majority of syntax and parsing errors, the AttributeError issue still persists. This seems to be caused by an existing bug in the rstcheck_core library. Below is the error message for reference:

An `AttributeError` error occured. This is most probably due to a code block directive (code/code-block/sourcecode) without a specified language. This may result in a false negative for source: '/home/runner/work/ansible-documentation/ansible-documentation/docs/docsite/rst/network/user_guide/platform_enos.rst'. The reason can also be another directive. For more information see the FAQ (https://rstcheck-core.rtfd.io/en/latest/faq) or the corresponding github issue: https://github.com/rstcheck/rstcheck-core/issues/3.

Would it be acceptable to ignore this issue given its root cause in the library? I appreciate your guidance on how to proceed.

@ganeshhubale Hi, I've looked through the errors in your branch. It seems there are some more instances of the missing language in code blocks triggering that error. For example, docs/docsite/rst/reference_appendices/general_precedence.rst

However it also looks like there are some cases of this bug showing up: rstcheck/rstcheck-core#63

I've observed this with the docs/docsite/rst/getting_started/basic_concepts.rst file. This file uses the .. include:: directive but does not contain the code block directive.

Have you been able to successfully ignore this? I've attempted via rstcheck.cfg but it doesn't seem to have any effect. Even if I set the report-level flag to ERROR, the warning still pops up:

$ rstcheck --version
rstcheck CLI Version: 6.2.4
rstcheck-core Version: 1.2.1

$ rstcheck docs/docsite/rst/getting_started/basic_concepts.rst --report-level=ERROR

[ganeshhubale]

@oraNod yes, I agree with you. about this issue - rstcheck/rstcheck-core#63 - Can we open this?

• If you want to use .rstcheck.cfg file for config then we need to add this file at parent(root) level directory where we have .rst files. But even I tried it with ignore-messages config; it does not avoid AttributeError warning.

• Even I tried with all the report-levels; it did not avoid warning message.

 > rstcheck docs/docsite/rst/getting_started/basic_concepts.rst --report-level=1
 
WARNING:rstcheck_core.checker:An `AttributeError` error occured. This is most probably due to a code block directive (code/code-block/sourcecode) without a specified language. This may result in a false negative for source: 'docs/docsite/rst/getting_started/basic_concepts.rst'. The reason can also be another directive. For more information see the FAQ (https://rstcheck-core.rtfd.io/en/latest/faq) or the corresponding github issue: https://github.com/rstcheck/rstcheck-core/issues/3.
Success! No issues detected.

> rstcheck docs/docsite/rst/getting_started/basic_concepts.rst --report-level=2

WARNING:rstcheck_core.checker:An `AttributeError` error occured. This is most probably due to a code block directive (code/code-block/sourcecode) without a specified language. This may result in a false negative for source: 'docs/docsite/rst/getting_started/basic_concepts.rst'. The reason can also be another directive. For more information see the FAQ (https://rstcheck-core.rtfd.io/en/latest/faq) or the corresponding github issue: https://github.com/rstcheck/rstcheck-core/issues/3.
Success! No issues detected.

 > rstcheck docs/docsite/rst/getting_started/basic_concepts.rst --report-level=3
 
WARNING:rstcheck_core.checker:An `AttributeError` error occured. This is most probably due to a code block directive (code/code-block/sourcecode) without a specified language. This may result in a false negative for source: 'docs/docsite/rst/getting_started/basic_concepts.rst'. The reason can also be another directive. For more information see the FAQ (https://rstcheck-core.rtfd.io/en/latest/faq) or the corresponding github issue: https://github.com/rstcheck/rstcheck-core/issues/3.
Success! No issues detected.

 > rstcheck docs/docsite/rst/getting_started/basic_concepts.rst --report-level=4
 
WARNING:rstcheck_core.checker:An `AttributeError` error occured. This is most probably due to a code block directive (code/code-block/sourcecode) without a specified language. This may result in a false negative for source: 'docs/docsite/rst/getting_started/basic_concepts.rst'. The reason can also be another directive. For more information see the FAQ (https://rstcheck-core.rtfd.io/en/latest/faq) or the corresponding github issue: https://github.com/rstcheck/rstcheck-core/issues/3.
Success! No issues detected.

> rstcheck docs/docsite/rst/getting_started/basic_concepts.rst --report-level=5

WARNING:rstcheck_core.checker:An `AttributeError` error occured. This is most probably due to a code block directive (code/code-block/sourcecode) without a specified language. This may result in a false negative for source: 'docs/docsite/rst/getting_started/basic_concepts.rst'. The reason can also be another directive. For more information see the FAQ (https://rstcheck-core.rtfd.io/en/latest/faq) or the corresponding github issue: https://github.com/rstcheck/rstcheck-core/issues/3.
Success! No issues detected.

• But when I updated config with report_level=1 in rstcheck.py file. I can see only INFO error as expected.

code block:

 config = RstcheckConfig(
        ignore_roles=[
            "ansplugin", "ansopt", "ansretval", "ansval", "ansenvvar", "ansenvvarref"
        ],
        ignore_substitutions=["br"],
        report_level=1,  # Adjust report level as needed -> ["info": 1, "warning": 2, "error": 3,"severe": 4, "none": 5,]
        recursive=True,          # Set to True to check directories recursively
    )

> python tests/checkers.py rstcheck

/Users/ganesh/work/ansible/docs-project/ansible-documentation/docs/docsite/rst/porting_guides/porting_guide_4.rst:228: (INFO/1) Duplicate implicit target name: "deprecated features".
/Users/ganesh/work/ansible/docs-project/ansible-documentation/docs/docsite/rst/porting_guides/porting_guide_4.rst:236: (INFO/1) Duplicate implicit target name: "cisco.nxos".
/Users/ganesh/work/ansible/docs-project/ansible-documentation/docs/docsite/rst/porting_guides/porting_guide_4.rst:246: (INFO/1) Duplicate implicit target name: "junipernetworks.junos".
/Users/ganesh/work/ansible/docs-project/ansible-documentation/docs/docsite/rst/porting_guides/porting_guide_4.rst:254: (INFO/1) Duplicate implicit target name: "major changes".
/Users/ganesh/work/ansible/docs-project/ansible-documentation/docs/docsite/rst/porting_guides/porting_guide_4.rst:257: (INFO/1) Duplicate implicit target name: "containers.podman".
/Users/ganesh/work/ansible/docs-project/ansible-documentation/docs/docsite/rst/porting_guides/porting_guide_4.rst:268: (INFO/1) Duplicate implicit target name: "deprecated features".
/Users/ganesh/work/ansible/docs-project/ansible-documentation/docs/docsite/rst/porting_guides/porting_guide_4.rst:279: (INFO/1) Duplicate implicit target name: "major changes".
/Users/ganesh/work/ansible/docs-project/ansible-documentation/docs/docsite/rst/porting_guides/porting_guide_4.rst:292: (INFO/1) Duplicate implicit target name: "deprecated features".
/Users/ganesh/work/ansible/docs-project/ansible-documentation/docs/docsite/rst/porting_guides/porting_guide_4.rst:300: (INFO/1) Duplicate implicit target name: "cisco.ios".
/Users/ganesh/work/ansible/docs-project/ansible-documentation/docs/docsite/rst/porting_guides/porting_guide_4.rst:306: (INFO/1) Duplicate implicit target name: "junipernetworks.junos".

Please help me with next steps.

Thanks!

[oraNod]

@ganeshhubale Thanks for keeping going with this! That looks promising. I guess it's a bit weird though because info seems to be the default level according to the docs.

I also don't particularly like the idea of adding an rstcheck cfg file to the repo anyway to avoid clutter. I did try to add a section to the project toml but it didn't appear to have an effect. Anyway...

Thinking about next steps:

• Before we set this in the config I think it's worth making sure we address any other instances of code blocks that are missing a language, like the one in docs/docsite/rst/reference_appendices/general_precedence.rst - Let me know if you want some help and I can push to your branch.

• Regarding those duplicate target names in the porting guide. That might be another snag. Those porting guides are generated and we shouldn't edit them directly. It doesn't look like there is a way to exclude files from rstcheck, which would be the preferred option imo. @felixfontein @samccann Any thoughts on this one? Should we go back and address any porting guide issues separately?

[ganeshhubale]

• Before we set this in the config I think it's worth making sure we address any other instances of code blocks that are missing a language, like the one in docs/docsite/rst/reference_appendices/general_precedence.rst - Let me know if you want some help and I can push to your branch.

@oraNod You can push to this branch. As I am not getting what I can update to these files?
I can follow one push some changes to this branch.

[felixfontein]

There are quite a few changes of yaml to ini. This is wrong in most cases. It usually should be yaml or yaml+jinja (depending on whether strings are templated).

[felixfontein]

Regarding those duplicate target names in the porting guide. That might be another snag. Those porting guides are generated and we shouldn't edit them directly. It doesn't look like there is a way to exclude files from rstcheck, which would be the preferred option imo. @felixfontein @samccann Any thoughts on this one? Should we go back and address any porting guide issues separately?

Since we call rstcheck from a script, we could simply enumerate all files that we want to be checked and ask rstcheck to only check these.

[oraNod]

Regarding those duplicate target names in the porting guide. That might be another snag. Those porting guides are generated and we shouldn't edit them directly. It doesn't look like there is a way to exclude files from rstcheck, which would be the preferred option imo. @felixfontein @samccann Any thoughts on this one? Should we go back and address any porting guide issues separately?

Since we call rstcheck from a script, we could simply enumerate all files that we want to be checked and ask rstcheck to only check these.

Excellent suggestion @felixfontein cheers

[oraNod]

@ganeshhubale I pushed a commit with a few more language specifiers for code-blocks. It appears that include:: directive is triggering the warning for several other files.

I'll try to take a more detailed look at this tomorrow or early next week. Thanks again for working on this.

[webknjaz]

Don't change the generated file by hand. This must be pinned with the integrated tooling.

[ganeshhubale]

Thanks you for your reviews.
I have updated using nox in new PR - #2383

[ganeshhubale]

@ganeshhubale I pushed a commit with a few more language specifiers for code-blocks. It appears that include:: directive is triggering the warning for several other files.

I'll try to take a more detailed look at this tomorrow or early next week. Thanks again for working on this.

Thank you @oraNod

[oraNod]

@ganeshhubale Hey, it seems like this PR has got a bit unwieldy. I've separated out the changes to add the language attribute to codeblocks in a new PR. Can you drop those commits from this PR to leave only the changes to the rstcheck script?

It might even be worth cherry picking the rstcheck script changes to a new branch and opening a fresh PR.

Final thing, and my bad for not pointing this out from the beginning, but as @webknjaz mentioned we have tooling in place to update the lock files so things like tests/requirements.txt should never be modified by hand. Please see the dependency files section of the README: https://github.com/ansible/ansible-documentation?tab=readme-ov-file#dependency-files

Give us a shout if you have any questions or need a hand with this. Thanks again for all the work you've put into this so far.

[felixfontein]

Regarding those duplicate target names in the porting guide. That might be another snag. Those porting guides are generated and we shouldn't edit them directly. It doesn't look like there is a way to exclude files from rstcheck, which would be the preferred option imo. @felixfontein @samccann Any thoughts on this one? Should we go back and address any porting guide issues separately?

Just FYI, the generated porting guides are now excluded from rstcheck. I had to implement that yesterday in #2376 to get the Ansible 11.2.0 release out.

[ganeshhubale]

@ganeshhubale Hey, it seems like this PR has got a bit unwieldy. I've separated out the changes to add the language attribute to codeblocks in a new PR. Can you drop those commits from this PR to leave only the changes to the rstcheck script?

It might even be worth cherry picking the rstcheck script changes to a new branch and opening a fresh PR.

Final thing, and my bad for not pointing this out from the beginning, but as @webknjaz mentioned we have tooling in place to update the lock files so things like tests/requirements.txt should never be modified by hand. Please see the dependency files section of the README: https://github.com/ansible/ansible-documentation?tab=readme-ov-file#dependency-files

Give us a shout if you have any questions or need a hand with this. Thanks again for all the work you've put into this so far.

@oraNod As you mentioned, I have moved required changes in rstcheck.py file to new PR - #2383

Please let me know if any changes needed.

Thanks for your support. 👍

[oraNod]

@ganeshhubale Thanks for keeping this contribution going! I'll close this PR now in favour of #2383