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

ganeshhubale · 2025-01-11T12:22:20Z

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

- 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. Signed-off-by: Ganesh Hubale <ganeshhubale03@gmail.com>

- Corrected YAML formatting issues, ensuring valid syntax for rstcheck validation. - Fixed malformed tables by aligning columns and ensuring consistent formatting. - Addressed unreferenced and duplicate hyperlink targets, ensuring proper references or removal of unused targets. - Adjusted invalid code block types (e.g., switching from yaml to ini or text) for compatibility with rstcheck. - Resolved custom role (ansplugin) issues by either ignoring the role. Signed-off-by: Ganesh Hubale <ganeshhubale03@gmail.com>

ansible-documentation-bot · 2025-01-11T18:17:44Z

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 · 2025-01-11T18:32:38Z

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 · 2025-01-13T15:06:25Z

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 · 2025-01-15T11:07:27Z

@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 · 2025-01-15T11:37:50Z

@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 · 2025-01-15T14:37:33Z

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 · 2025-01-15T18:33:43Z

docs/docsite/rst/collections_guide/collections_using_playbooks.rst

@@ -18,7 +18,7 @@ Once installed, you can reference a collection content by its fully qualified co

 This works for roles or any type of plugin distributed within the collection:

-.. code-block:: yaml
+.. code-block:: ini


Shouldn't this be yaml+jinja? This is definitely not an INI file.

felixfontein · 2025-01-15T18:34:43Z

docs/docsite/rst/dev_guide/developing_collections_creating.rst

@@ -90,7 +90,7 @@ A collection skeleton is a directory that looks like a collection directory but

 An example ``galaxy.yml.j2`` file that accepts an optional dictionary variable ``dependencies`` could look like this:

-.. code-block:: yaml
+.. code-block:: ini


I think this should be jinja, since it is a Jinja template (that will end up as YAML, but right now is not YAML). INI is definitely wrong here.

felixfontein · 2025-01-15T18:41:03Z

tests/checkers/rstcheck.py

@@ -1,63 +1,34 @@
-"""Sanity test using rstcheck and sphinx."""
-from __future__ import annotations


Please keep the header.

felixfontein · 2025-01-15T18:41:18Z

tests/checkers/rstcheck.py

-import re
-import subprocess
+from rstcheck_core.runner import RstcheckMainRunner
+from rstcheck_core.config import RstcheckConfig


So are you using rstcheck or rstcheck-core?

felixfontein · 2025-01-15T18:42:43Z

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 · 2025-01-16T18:52:38Z

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 · 2025-01-16T19:35:01Z

@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.

felixfontein · 2025-01-16T19:35:05Z

docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst

@@ -208,7 +208,7 @@ The ``Socket path does not exist or cannot be found``  and ``Unable to connect t

 For example:

-.. code-block:: none
+.. code-block:: json


Suggested change

.. code-block:: json

.. code-block:: ansible-output

felixfontein · 2025-01-16T19:35:15Z

docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst

@@ -221,7 +221,7 @@ For example:

 or

-.. code-block:: none
+.. code-block:: json


Suggested change

.. code-block:: json

.. code-block:: ansible-output

felixfontein · 2025-01-16T19:35:32Z

docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst

@@ -267,7 +267,7 @@ The ``unable to open shell`` message means that the ``ansible-connection`` daemo

 For example:

-.. code-block:: none
+.. code-block:: console


Suggested change

.. code-block:: console

.. code-block:: ansible-output

felixfontein · 2025-01-16T19:35:40Z

docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst

@@ -276,7 +276,7 @@ For example:
 or:


-.. code-block:: none
+.. code-block:: console


Suggested change

.. code-block:: console

.. code-block:: ansible-output

felixfontein · 2025-01-16T19:37:24Z

docs/docsite/rst/os_guide/windows_ssh.rst

@@ -128,7 +128,7 @@ SSH key authentication on Windows works in the same way as SSH key authenticatio

 One difference is that the ``authorized_keys`` file for admin users is not located in the ``.ssh`` folder in the user's profile directory but in ``C:\ProgramData\ssh\administrators_authorized_keys``. It is possible to change the location of the ``authorized_keys`` file for admin users back to the user profile directory by removing, or commenting, the lines in ``C:\ProgramData\ssh\sshd_config`` and restarting the ``sshd`` service.

-.. code-block::
+.. code-block:: shell


This is a SSH config file, not shell commands.

Suggested change

.. code-block:: shell

.. code-block:: text

felixfontein · 2025-01-16T19:39:30Z

docs/docsite/rst/reference_appendices/general_precedence.rst

@@ -167,7 +167,7 @@ This category only applies to things that take direct options, generally modules

 Outside of task actions, the most recognizable 'direct assignments' are with lookup, filter and test plugins:

-.. code::
+.. code:: jinja


jinja is for Jinja templates. If the following would be wrapped in {{ }} it would be the right lexer, but for pure Jinja code it is not.

python would work mostly, except for the |.

Maybe keep text here? Or add {{ }} around every non-empty line?

webknjaz · 2025-01-16T22:20:24Z

docs/docsite/rst/collections_guide/collections_installing.rst

@@ -185,7 +185,7 @@ Using locally installed collections adjacent to playbooks has some benefits, suc

 Here is an example of keeping a collection adjacent to the current playbook, under a ``collections/ansible_collections/`` directory structure.

-.. code-block:: text
+.. code-block:: console


It's not really console. Console is for snippets copied from terminal output, featuring a prompt followed by its command and then the output.

webknjaz · 2025-01-16T22:23:40Z

tests/checkers/rstcheck.py

-    ignore_substitutions = (
-        'br',
+    # Define the paths to check (passed as CLI arguments or from stdin)
+    paths = [pathlib.Path(p) for p in (sys.argv[1:] or sys.stdin.read().splitlines())]


This expression is unnecessarily complex. Split it.

webknjaz · 2025-01-16T22:24:27Z

tests/checkers/rstcheck.py


-if __name__ == '__main__':
+if __name__ == "__main__":


I recommend moving any formatting changes to a separate PR.

webknjaz · 2025-01-16T22:25:11Z

tests/requirements.txt

@@ -121,7 +121,7 @@ requests==2.32.3
    # via sphinx
 resolvelib==1.0.1
    # via -r tests/requirements-relaxed.in
-rstcheck==5.0.0
+rstcheck>=6.2.4


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

webknjaz · 2025-01-16T22:25:21Z

tests/constraints-base.in

@@ -1,4 +1,4 @@
 # Known limitations for indirect/transitive dependencies.

-rstcheck < 6  # rstcheck 6.x has problem with rstcheck.core triggered by include files w/ sphinx directives https://github.com/rstcheck/rstcheck-core/issues/3
+rstcheck>=6.2.4


Keep the previously sparse style.

Suggested change

rstcheck>=6.2.4

rstcheck >= 6.2.4

Actually, this file is the absolute wrong place for lower bounds. Its semantic purpose is to hold temporary exclusions, which this isn't.
The entry should be deleted instead.

Suggested change

rstcheck>=6.2.4

webknjaz · 2025-01-16T22:27:31Z

docs/docsite/rst/network/user_guide/network_resource_modules.rst

@@ -53,7 +53,7 @@ The following table shows an example of how an initial resource configuration ch
 +-----------------------------------------+------------------------------------+-----------------------------------------+
 | Resource starting configuration         | task-provided configuration (YAML) | Final resource configuration on device  |
 +=========================================+====================================+=========================================+
-| .. code-block:: text                    |  .. code-block:: yaml              | *merged*                                |
+| .. code-block:: text                    |  .. code-block:: ini               | *merged*                                | 


webknjaz · 2025-01-16T22:28:14Z

docs/docsite/rst/os_guide/intro_bsd.rst

@@ -157,7 +157,7 @@ The playbook below

 displays the details

-.. code-block:: yaml
+.. code-block:: shell


This is either console or ansible-output. It's not a shell script.

Suggested change

.. code-block:: shell

.. code-block:: ansible-output

ganeshhubale · 2025-01-17T02:25:21Z

@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

ganeshhubale temporarily deployed to github-bot January 11, 2025 12:22 — with GitHub Actions Inactive

ganeshhubale temporarily deployed to github-bot January 11, 2025 18:17 — with GitHub Actions Inactive

felixfontein reviewed Jan 15, 2025

View reviewed changes

fixing up some code-block language specifiers

5858fe2

oraNod temporarily deployed to github-bot January 16, 2025 19:31 — with GitHub Actions Inactive

felixfontein reviewed Jan 16, 2025

View reviewed changes

webknjaz reviewed Jan 16, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

ganeshhubale commented Jan 11, 2025

ansible-documentation-bot bot commented Jan 11, 2025

ganeshhubale commented Jan 11, 2025

oraNod commented Jan 13, 2025

ganeshhubale commented Jan 15, 2025

oraNod commented Jan 15, 2025

ganeshhubale commented Jan 15, 2025 •

edited

Loading

felixfontein left a comment

felixfontein Jan 15, 2025

webknjaz Jan 16, 2025

felixfontein Jan 15, 2025

felixfontein Jan 15, 2025

felixfontein Jan 15, 2025

felixfontein commented Jan 15, 2025

oraNod commented Jan 16, 2025

oraNod commented Jan 16, 2025

felixfontein Jan 16, 2025

felixfontein Jan 16, 2025

felixfontein Jan 16, 2025

felixfontein Jan 16, 2025

felixfontein Jan 16, 2025

felixfontein Jan 16, 2025

webknjaz Jan 16, 2025

webknjaz Jan 16, 2025

webknjaz Jan 16, 2025

webknjaz Jan 16, 2025

webknjaz Jan 16, 2025

webknjaz Jan 16, 2025

webknjaz Jan 16, 2025

webknjaz Jan 16, 2025

ganeshhubale commented Jan 17, 2025

		@@ -1,63 +1,34 @@
		"""Sanity test using rstcheck and sphinx."""
		from __future__ import annotations

	\| .. code-block:: text \| .. code-block:: ini \| merged \|
	\| .. code-block:: text \| .. code-block:: yaml \| merged \|

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

Are you sure you want to change the base?

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

Conversation

ganeshhubale commented Jan 11, 2025

ansible-documentation-bot bot commented Jan 11, 2025

ganeshhubale commented Jan 11, 2025

oraNod commented Jan 13, 2025

ganeshhubale commented Jan 15, 2025

oraNod commented Jan 15, 2025

ganeshhubale commented Jan 15, 2025 • edited Loading

felixfontein left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

felixfontein commented Jan 15, 2025

oraNod commented Jan 16, 2025

oraNod commented Jan 16, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ganeshhubale commented Jan 17, 2025

ganeshhubale commented Jan 15, 2025 •

edited

Loading