[docutils]: Add annotations for `docutils.parsers.rst.states`

[Harry-Lees]

Linked Issue: #14031

This PR overlaps with #14191, apologies to @donBarbos, I didn't see your PR while working on this. I think this PR is a more fully implemented version of annotations in docutils.parsers.rst.states, but #14191 covers significantly more than just this file.

It might be possible to merge the two together, I will check the other PR to ensure that they line up on the parts which are overlapping.

Edit: I merged some changes where I thought #14191's implementation was more complete than this one, I added Co-authored attribution to the relevant commits, @donBarbos if you are unhappy in any way with the attribution, please let me know how I can update it, I'm not too well versed in Git, but I think I can transfer the commit ownership entirely, or remove you from the commit(s) entirely if you're unhappy to have your name associated with them :)

[github-actions[bot]]

Diff from mypy_primer, showing the effect of this PR on open source code:

sphinx (https://github.com/sphinx-doc/sphinx)
- sphinx/directives/other.py:10: note: In module imported here:
+ sphinx/domains/__init__.py:22: note: In module imported here:
+ sphinx/util/docutils.py: note: In member "get_source_info" of class "SphinxDirective":
+ sphinx/util/docutils.py:488:16: error: Incompatible return value type (got "tuple[str, int] | tuple[None, None]", expected "tuple[str, int]")  [return-value]
+ sphinx/directives/__init__.py: note: In member "run" of class "DefaultRole":
+ sphinx/directives/__init__.py:332:24: error: "RSTStateMachine" has no attribute "language"  [attr-defined]
+ sphinx/ext/autosummary/__init__.py: note: In function "extract_summary":
+ sphinx/ext/autosummary/__init__.py:603:41: error: Argument 1 to "RSTStateMachine" has incompatible type "tuple[Body, BulletList, DefinitionList, EnumeratedList, FieldList, OptionList, LineBlock, ExtensionOptions, Explicit, Text, Definition, Line, SubstitutionDef, RFC2822Body, RFC2822List]"; expected "Iterable[type[State[Any]]]"  [arg-type]
+ sphinx/directives/other.py: note: In member "run" of class "Include":
+ sphinx/directives/other.py:409:13: error: Cannot assign to a method  [method-assign]
+ sphinx/directives/other.py:409:47: error: Incompatible types in assignment (expression has type "Callable[[list[str], str], None]", variable has type "Callable[[list[str] | StringList, str], None]")  [assignment]
+ sphinx/directives/code.py: note: In member "run" of class "CodeBlock":
+ sphinx/directives/code.py:146:74: error: Argument "location" to "dedent_lines" has incompatible type "tuple[str, int] | tuple[None, None]"; expected "tuple[str, int] | None"  [arg-type]
+ sphinx/directives/code.py: note: In member "run" of class "LiteralInclude":
+ sphinx/directives/code.py:462:48: error: Argument "location" to "read" of "LiteralIncludeReader" has incompatible type "tuple[str, int] | tuple[None, None]"; expected "tuple[str, int] | None"  [arg-type]
+ sphinx/ext/graphviz.py: note: In member "run" of class "Graphviz":
+ sphinx/ext/graphviz.py:163:21: error: "RSTStateMachine" has no attribute "reporter"  [attr-defined]

bokeh (https://github.com/bokeh/bokeh)
- src/bokeh/sphinxext/bokeh_palette_group.py:53: note: In module imported here:
+ src/bokeh/sphinxext/bokeh_palette_group.py:53: note: ... from here:

[github-actions[bot]]

Diff from mypy_primer, showing the effect of this PR on open source code:

sphinx (https://github.com/sphinx-doc/sphinx)
- sphinx/directives/other.py:10: note: In module imported here:
+ sphinx/domains/__init__.py:22: note: In module imported here:
+ sphinx/util/docutils.py: note: In member "get_source_info" of class "SphinxDirective":
+ sphinx/util/docutils.py:488:16: error: Incompatible return value type (got "tuple[str, int] | tuple[None, None]", expected "tuple[str, int]")  [return-value]
+ sphinx/directives/__init__.py: note: In member "run" of class "DefaultRole":
+ sphinx/directives/__init__.py:332:24: error: Argument 2 to "role" has incompatible type "_RstLanguageModule"; expected "_LanguageModule"  [arg-type]
+ sphinx/ext/autosummary/__init__.py: note: In function "extract_summary":
+ sphinx/ext/autosummary/__init__.py:603:41: error: Argument 1 to "RSTStateMachine" has incompatible type "tuple[Body, BulletList, DefinitionList, EnumeratedList, FieldList, OptionList, LineBlock, ExtensionOptions, Explicit, Text, Definition, Line, SubstitutionDef, RFC2822Body, RFC2822List]"; expected "Iterable[type[State[Any]]]"  [arg-type]
+ sphinx/directives/other.py: note: In member "run" of class "Include":
+ sphinx/directives/other.py:409:13: error: Cannot assign to a method  [method-assign]
+ sphinx/directives/other.py:409:47: error: Incompatible types in assignment (expression has type "Callable[[list[str], str], None]", variable has type "Callable[[list[str] | StringList, str], None]")  [assignment]
+ sphinx/directives/code.py: note: In member "run" of class "CodeBlock":
+ sphinx/directives/code.py:146:74: error: Argument "location" to "dedent_lines" has incompatible type "tuple[str, int] | tuple[None, None]"; expected "tuple[str, int] | None"  [arg-type]
+ sphinx/directives/code.py: note: In member "run" of class "LiteralInclude":
+ sphinx/directives/code.py:462:48: error: Argument "location" to "read" of "LiteralIncludeReader" has incompatible type "tuple[str, int] | tuple[None, None]"; expected "tuple[str, int] | None"  [arg-type]

bokeh (https://github.com/bokeh/bokeh)
- src/bokeh/sphinxext/bokeh_palette_group.py:53: note: In module imported here:
+ src/bokeh/sphinxext/bokeh_palette_group.py:53: note: ... from here:

[github-actions[bot]]

Diff from mypy_primer, showing the effect of this PR on open source code:

sphinx (https://github.com/sphinx-doc/sphinx)
- sphinx/directives/other.py:10: note: In module imported here:
+ sphinx/util/docutils.py: note: In member "get_source_info" of class "SphinxDirective":
+ sphinx/util/docutils.py:488:16: error: Incompatible return value type (got "tuple[str, int] | tuple[None, None]", expected "tuple[str, int]")  [return-value]
+ sphinx/directives/__init__.py: note: In member "run" of class "DefaultRole":
+ sphinx/directives/__init__.py:332:24: error: Argument 2 to "role" has incompatible type "_RstLanguageModule"; expected "_LanguageModule"  [arg-type]
+ sphinx/ext/autosummary/__init__.py: note: In function "extract_summary":
+ sphinx/ext/autosummary/__init__.py:603:41: error: Argument 1 to "RSTStateMachine" has incompatible type "tuple[Body, BulletList, DefinitionList, EnumeratedList, FieldList, OptionList, LineBlock, ExtensionOptions, Explicit, Text, Definition, Line, SubstitutionDef, RFC2822Body, RFC2822List]"; expected "Iterable[type[State[Any]]]"  [arg-type]
+ sphinx/directives/other.py: note: In member "run" of class "Include":
+ sphinx/directives/other.py:409:13: error: Cannot assign to a method  [method-assign]
+ sphinx/directives/other.py:409:47: error: Incompatible types in assignment (expression has type "Callable[[list[str], str], None]", variable has type "Callable[[list[str] | StringList, str], None]")  [assignment]
+ sphinx/directives/code.py: note: In member "run" of class "CodeBlock":
+ sphinx/directives/code.py:146:74: error: Argument "location" to "dedent_lines" has incompatible type "tuple[str, int] | tuple[None, None]"; expected "tuple[str, int] | None"  [arg-type]
+ sphinx/directives/code.py: note: In member "run" of class "LiteralInclude":
+ sphinx/directives/code.py:462:48: error: Argument "location" to "read" of "LiteralIncludeReader" has incompatible type "tuple[str, int] | tuple[None, None]"; expected "tuple[str, int] | None"  [arg-type]

bokeh (https://github.com/bokeh/bokeh)
- src/bokeh/sphinxext/bokeh_palette_group.py:53: note: In module imported here:

[donbarbos]

Thank you, I suggest merging my PR first and then we can see what improvements you have made ;)

I will also note that stubs for docutils are already fully generated in my draft PR (WIP) and for now I am sorting out the errors and sending separate updates for directories

[srittau]

I've merged @donBarbos's PR. This now has (as expected) merge conflicts.

[Harry-Lees]

I rebased the PR and fixed a couple of obvious errors, I'm sure the CI will have some failures as-well :D.

I need to take a more detailed look at some of the differences, I should be able to get round to it later today.

[github-actions[bot]]

Diff from mypy_primer, showing the effect of this PR on open source code:

sphinx (https://github.com/sphinx-doc/sphinx)
+ sphinx/ext/autosummary/__init__.py: note: In function "extract_summary":
+ sphinx/ext/autosummary/__init__.py:603:41: error: Argument 1 to "RSTStateMachine" has incompatible type "tuple[Body, BulletList, DefinitionList, EnumeratedList, FieldList, OptionList, LineBlock, ExtensionOptions, Explicit, Text, Definition, Line, SubstitutionDef, RFC2822Body, RFC2822List]"; expected "Iterable[type[State[list[str]]]]"  [arg-type]

[github-actions[bot]]

Diff from mypy_primer, showing the effect of this PR on open source code:

sphinx (https://github.com/sphinx-doc/sphinx)
+ sphinx/domains/__init__.py:22: note: In module imported here:

bokeh (https://github.com/bokeh/bokeh)
+ src/bokeh/sphinxext/_internal/bokeh_palette_group.py:43: note: ... from here:

[github-actions[bot]]

According to mypy_primer, this change has no effect on the checked open source code. 🤖🎉

[github-actions[bot]]

According to mypy_primer, this change has no effect on the checked open source code. 🤖🎉