autodoc: add :novalue: option #8222

marlonjames · 2020-09-18T20:26:45Z

Subject: Add :novalue: option to display type hint but remove value

Feature or Bugfix

Feature

Purpose

When documenting using the .. autodata:: directive, the :annotation: option only allows displaying nothing or replacing the annotation manually.
This adds the :novalue: option which will display the type hint but not the value.

Detail

When the :annotation: option is used, the current behavior is preserved, and :novalue: option does nothing.
When :novalue: is used by itself, the value will not be displayed but any type hint will.

Relates

#8209

When the :annotation: option is not used, the :novalue: option may be used to remove the value. This is useful when you want to display the type hint but not the value, and you don't want to specify the annotation manually.

doc/usage/extensions/autodoc.rst

Add tests for autodata directive options :annotation: and :novalue:.

ktbarrett · 2020-09-27T00:19:28Z

To clarify, this exists to support Python 3.5 and 2.7 compliant codebases where uninitialized variables cannot exist, but they still want to use type hints with Sphinx autodoc. Support for this case is currently missing.

tk0miya

Now both python 3.5 and 2.7 reached EOL. So I wonder this is still needed.

tk0miya · 2020-10-03T03:54:57Z

doc/usage/extensions/autodoc.rst

@@ -326,6 +326,15 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
   By default, without ``annotation`` option, Sphinx tries to obtain the value of
   the variable and print it after the name.

+   The ``novalue`` option can be used instead of a blank ``annotation`` to show the


In autodoc, we usually use no- prefix to disable some feature (ex. no-members). So it is better to rename this to no-value (if we adopted this proposal)

Suggested change

The ``novalue`` option can be used instead of a blank ``annotation`` to show the

The ``no-value`` option can be used instead of a blank ``annotation`` to show the

Would that imply this PR would require implementing the non-negated version of :value: as well?

If somebody requests it. But there are no such requests now, AFAIK.

ktbarrett · 2020-10-13T16:53:48Z

doc/usage/extensions/autodoc.rst

@@ -326,6 +326,15 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
   By default, without ``annotation`` option, Sphinx tries to obtain the value of
   the variable and print it after the name.

+   The ``novalue`` option can be used instead of a blank ``annotation`` to show the


Suggested change

The ``novalue`` option can be used instead of a blank ``annotation`` to show the

The ``no-value`` option can be used instead of a blank ``annotation`` to show the

ktbarrett · 2020-10-13T16:53:59Z

doc/usage/extensions/autodoc.rst

+   type hint but not the value::
+
+      .. autodata:: CD_DRIVE
+         :novalue:


Suggested change

:novalue:

:no-value:

ktbarrett · 2020-10-13T16:54:10Z

doc/usage/extensions/autodoc.rst

+      .. autodata:: CD_DRIVE
+         :novalue:
+
+   If both the ``annotation`` and ``novalue`` options are used, ``novalue`` has no


Suggested change

If both the ``annotation`` and ``novalue`` options are used, ``novalue`` has no

If both the ``annotation`` and ``no-value`` options are used, ``no-value`` has no

ktbarrett · 2020-10-13T16:54:24Z

doc/usage/extensions/autodoc.rst

@@ -365,6 +374,9 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
      option.
   .. versionchanged:: 2.0
      :rst:dir:`autodecorator` added.
+   .. versionchanged:: 3.3
+      :rst:dir:`autodata` and :rst:dir:`autoattribute` now have a ``novalue``


Suggested change

:rst:dir:`autodata` and :rst:dir:`autoattribute` now have a ``novalue``

:rst:dir:`autodata` and :rst:dir:`autoattribute` now have a ``no-value``

ktbarrett · 2020-10-13T16:54:34Z

sphinx/ext/autodoc/__init__.py

@@ -1598,6 +1598,7 @@ class DataDocumenter(ModuleLevelDocumenter):
    priority = -10
    option_spec = dict(ModuleLevelDocumenter.option_spec)
    option_spec["annotation"] = annotation_option
+    option_spec["novalue"] = bool_option


Suggested change

option_spec["novalue"] = bool_option

option_spec["no-value"] = bool_option

ktbarrett · 2020-10-13T17:06:12Z

doc/usage/extensions/autodoc.rst

@@ -326,6 +326,15 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
   By default, without ``annotation`` option, Sphinx tries to obtain the value of
   the variable and print it after the name.

+   The ``novalue`` option can be used instead of a blank ``annotation`` to show the


Would that imply this PR would require implementing the non-negated version of :value: as well?

tk0miya · 2020-11-01T05:41:37Z

doc/usage/extensions/autodoc.rst

@@ -326,6 +326,15 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
   By default, without ``annotation`` option, Sphinx tries to obtain the value of
   the variable and print it after the name.

+   The ``novalue`` option can be used instead of a blank ``annotation`` to show the


If somebody requests it. But there are no such requests now, AFAIK.

tk0miya · 2020-11-01T05:42:36Z

doc/usage/extensions/autodoc.rst

@@ -365,6 +374,9 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
      option.
   .. versionchanged:: 2.0
      :rst:dir:`autodecorator` added.
+   .. versionchanged:: 3.3


I determined to merge this into 3.4. Please update this.

tk0miya · 2020-11-01T06:06:28Z

tests/roots/test-ext-autodoc/index.rst

@@ -11,3 +11,16 @@
 .. autofunction:: target.typehints.incr

 .. autofunction:: target.typehints.tuple_args
+
+.. autodata:: target.typed_vars_py35.attr1


Basically, we don't need to update this file because we have do_autodoc() helper.

tk0miya · 2020-11-01T06:08:51Z

tests/roots/test-ext-autodoc/target/typed_vars_py35.py

@@ -0,0 +1,11 @@
+#: attr1


py35 suffix is no longer needed because Sphinx supports py35 or above.

I think no-value option is not related to "typed variables" at all. So no reason to add new examples. How about using target.integer instead?

tk0miya · 2020-11-01T06:23:53Z

tests/test_ext_autodoc.py

@@ -2024,6 +2025,151 @@ def test_pyclass_for_ClassLevelDocumenter(app):
    ]


+@pytest.mark.skipif(sys.version_info < (3, 6), reason='py36+ is available since python3.6.')
+@pytest.mark.sphinx('html', testroot='ext-autodoc')
+def test_pydata_for_DataDeclarationDocumenter(app):


Is there any reason to test with all of data-declaration, py36-style typed attributes and py35-style typed attributes?

tk0miya · 2020-11-14T17:32:37Z

Now I posted #8424 as a refined version of this PR. I'd like to merge it instead of this in a few days. Please let me know your opinion :-)

marlonjames force-pushed the autodoc_novalue branch from 4bb9a51 to f0f291e Compare September 19, 2020 05:13

autodoc: add :novalue: option

fc38e98

When the :annotation: option is not used, the :novalue: option may be used to remove the value. This is useful when you want to display the type hint but not the value, and you don't want to specify the annotation manually.

marlonjames force-pushed the autodoc_novalue branch from f0f291e to 026a31d Compare September 19, 2020 05:17

marlonjames mentioned this pull request Sep 21, 2020

Fixup documentation for global variables. cocotb/cocotb#2069

Closed

cmarqu reviewed Sep 21, 2020

View reviewed changes

doc/usage/extensions/autodoc.rst Show resolved Hide resolved

marlonjames and others added 2 commits September 22, 2020 11:05

autodoc: document :novalue: option

c5d06f6

autodoc: test autodata options

877de00

Add tests for autodata directive options :annotation: and :novalue:.

marlonjames force-pushed the autodoc_novalue branch from 026a31d to 877de00 Compare September 22, 2020 18:06

tk0miya reviewed Oct 3, 2020

View reviewed changes

tk0miya added extensions:autodoc type:proposal a feature suggestion labels Oct 3, 2020

tk0miya added this to the 3.4.0 milestone Oct 3, 2020

ktbarrett reviewed Oct 13, 2020

View reviewed changes

tk0miya modified the milestones: 3.4.0, 3.3.0 Nov 1, 2020

tk0miya reviewed Nov 1, 2020

View reviewed changes

tk0miya added a commit to tk0miya/sphinx that referenced this pull request Nov 14, 2020

Update CHANGES for PR sphinx-doc#8222

2b0f2db

tk0miya added a commit to tk0miya/sphinx that referenced this pull request Nov 14, 2020

Update CHANGES for PR sphinx-doc#8222

30d116e

tk0miya mentioned this pull request Nov 14, 2020

autodoc: Add :no-value: option to autoattribute and autodata to suppress the default value of the variable #8424

Merged

tk0miya added a commit to tk0miya/sphinx that referenced this pull request Nov 15, 2020

Update CHANGES for PR sphinx-doc#8222

80f6fb3

tk0miya added a commit to tk0miya/sphinx that referenced this pull request Nov 15, 2020

Update CHANGES for PR sphinx-doc#8222

a4ccca7

marlonjames closed this Nov 17, 2020

github-actions bot locked as resolved and limited conversation to collaborators Jul 21, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

autodoc: add :novalue: option #8222

autodoc: add :novalue: option #8222

marlonjames commented Sep 18, 2020 •

edited

Loading

ktbarrett commented Sep 27, 2020

tk0miya left a comment

tk0miya Oct 3, 2020

ktbarrett Oct 13, 2020

ktbarrett Oct 13, 2020

tk0miya Nov 1, 2020

ktbarrett Oct 13, 2020

ktbarrett Oct 13, 2020

ktbarrett Oct 13, 2020

ktbarrett Oct 13, 2020

ktbarrett Oct 13, 2020

ktbarrett Oct 13, 2020

tk0miya Nov 1, 2020

tk0miya Nov 1, 2020

tk0miya Nov 1, 2020

tk0miya Nov 1, 2020

tk0miya Nov 1, 2020

tk0miya commented Nov 14, 2020

	The ``novalue`` option can be used instead of a blank ``annotation`` to show the
	The ``no-value`` option can be used instead of a blank ``annotation`` to show the

	If both the ``annotation`` and ``novalue`` options are used, ``novalue`` has no
	If both the ``annotation`` and ``no-value`` options are used, ``no-value`` has no

	:rst:dir:`autodata` and :rst:dir:`autoattribute` now have a ``novalue``
	:rst:dir:`autodata` and :rst:dir:`autoattribute` now have a ``no-value``

	option_spec["novalue"] = bool_option
	option_spec["no-value"] = bool_option

autodoc: add :novalue: option #8222

autodoc: add :novalue: option #8222

Conversation

marlonjames commented Sep 18, 2020 • edited Loading

Feature or Bugfix

Purpose

Detail

Relates

ktbarrett commented Sep 27, 2020

tk0miya 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

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

tk0miya commented Nov 14, 2020

marlonjames commented Sep 18, 2020 •

edited

Loading