From 69d93c967c591a65f10bcb9cb07e03d5cf03cce6 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sat, 1 Jun 2019 23:18:37 +0900 Subject: [PATCH 1/6] Fix #1063: autodoc: automodule directive handles undocumented module level variables --- CHANGES | 2 ++ sphinx/ext/autodoc/__init__.py | 13 ++++++++-- tests/roots/test-ext-autodoc/target/module.py | 4 ++++ tests/test_autodoc.py | 24 +++++++++++++++++++ 4 files changed, 41 insertions(+), 2 deletions(-) create mode 100644 tests/roots/test-ext-autodoc/target/module.py diff --git a/CHANGES b/CHANGES index 2363ea759..c228978ec 100644 --- a/CHANGES +++ b/CHANGES @@ -90,6 +90,8 @@ Features added autodoc considers values as a docstring of the attribute * #6361: autodoc: Add :confval:`autodoc_typehints` to suppress typehints from signature +* #1063: autodoc: ``automodule`` directive now handles undocumented module level + variables * #6212 autosummary: Add :confval:`autosummary_imported_members` to display imported members on autosummary * #6271: ``make clean`` is catastrophically broken if building into '.' diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py index 7172553ac..f66269a6b 100644 --- a/sphinx/ext/autodoc/__init__.py +++ b/sphinx/ext/autodoc/__init__.py @@ -549,8 +549,10 @@ class Documenter: if self.analyzer: attr_docs = self.analyzer.find_attr_docs() + tagorder = self.analyzer.tagorder else: attr_docs = {} + tagorder = {} # process members and determine which to skip for (membername, member) in members: @@ -580,12 +582,13 @@ class Documenter: membername in self.options.special_members: keep = has_doc or self.options.undoc_members elif (namespace, membername) in attr_docs: + has_doc = bool(attr_docs[namespace, membername]) if want_all and membername.startswith('_'): # ignore members whose name starts with _ by default - keep = self.options.private_members + keep = has_doc and self.options.private_members else: # keep documented attributes - keep = True + keep = has_doc isattr = True elif want_all and membername.startswith('_'): # ignore members whose name starts with _ by default @@ -594,6 +597,8 @@ class Documenter: else: # ignore undocumented members if :undoc-members: is not given keep = has_doc or self.options.undoc_members + # module top level item or not + isattr = membername in tagorder # give the user a chance to decide whether this member # should be skipped @@ -1291,6 +1296,10 @@ class DataDocumenter(ModuleLevelDocumenter): return self.get_attr(self.parent or self.object, '__module__', None) \ or self.modname + def get_doc(self, encoding=None, ignore=1): + # type: (str, int) -> List[List[str]] + return [] + class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter): # type: ignore """ diff --git a/tests/roots/test-ext-autodoc/target/module.py b/tests/roots/test-ext-autodoc/target/module.py new file mode 100644 index 000000000..d5b557d94 --- /dev/null +++ b/tests/roots/test-ext-autodoc/target/module.py @@ -0,0 +1,4 @@ +#: docstring for CONSTANT1 +CONSTANT1 = "" + +CONSTANT2 = "" diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py index f6f5a618c..518d23e8c 100644 --- a/tests/test_autodoc.py +++ b/tests/test_autodoc.py @@ -1689,6 +1689,30 @@ def test_partialmethod(app): assert list(actual) == expected +@pytest.mark.usefixtures('setup_test') +def test_module_variables(): + options = {"members": None, + "undoc-members": True} + actual = do_autodoc(app, 'module', 'target.module', options) + assert list(actual) == [ + '', + '.. py:module:: target.module', + '', + '', + '.. py:data:: CONSTANT1', + ' :module: target.module', + " :annotation: = ''", + '', + ' docstring for CONSTANT1', + ' ', + '', + '.. py:data:: CONSTANT2', + ' :module: target.module', + " :annotation: = ''", + '', + ] + + @pytest.mark.sphinx('html', testroot='ext-autodoc') def test_autodoc_typehints_signature(app): app.config.autodoc_typehints = "signature" From 1303ea7cdfcba470e0ec35a9d5afb28f56a8a567 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sun, 2 Jun 2019 18:18:55 +0900 Subject: [PATCH 2/6] docs: Use directive:option in extensions/graphviz --- doc/usage/extensions/graphviz.rst | 107 +++++++++++++++++++++++++----- 1 file changed, 92 insertions(+), 15 deletions(-) diff --git a/doc/usage/extensions/graphviz.rst b/doc/usage/extensions/graphviz.rst index 4d801d346..e5633c481 100644 --- a/doc/usage/extensions/graphviz.rst +++ b/doc/usage/extensions/graphviz.rst @@ -39,6 +39,45 @@ It adds these directives: .. versionchanged:: 1.1 Added support for external files. + .. rubric:: options + + .. rst:directive:option:: alt: alternate text + :type: text + + The alternate text of the graph. By default, the graph code is used to + the alternate text. + + .. versionadded:: 1.0 + + .. rst:directive:option:: align: alignment of the graph + :type: left, center or right + + The horizontal alignment of the graph. + + .. versionadded:: 1.5 + + .. rst:directive:option:: caption: caption of the graph + :type: text + + The caption of the graph. + + .. versionadded:: 1.1 + + .. rst:directive:option:: graphviz_dot: dot command of the graph + :type: text + + The graphviz command (ex. ``dot``, ``neato`` and so on) for rendering the + graph. By default, :confval:`graphviz_dot` is used. + + .. versionadded:: 1.4 + + .. rst:directive:option:: name: label + :type: text + + The label of the graph. + + .. versionadded:: 1.6 + .. rst:directive:: graph @@ -56,6 +95,35 @@ It adds these directives: non-alphanumeric characters (e.g. a dash), you will have to double-quote it. + .. rubric:: options + + Same as :rst:dir:`graphviz`. + + .. rst:directive:option:: alt: alternate text + :type: text + + .. versionadded:: 1.0 + + .. rst:directive:option:: align: alignment of the graph + :type: left, center or right + + .. versionadded:: 1.5 + + .. rst:directive:option:: caption: caption of the graph + :type: text + + .. versionadded:: 1.1 + + .. rst:directive:option:: graphviz_dot: dot command of the graph + :type: text + + .. versionadded:: 1.4 + + .. rst:directive:option:: name: label + :type: text + + .. versionadded:: 1.6 + .. rst:directive:: digraph @@ -69,26 +137,35 @@ It adds these directives: "bar" -> "baz" -> "quux"; + .. rubric:: options -.. versionadded:: 1.0 - All three directives support an ``alt`` option that determines the image's - alternate text for HTML output. If not given, the alternate text defaults to - the graphviz code. + Same as :rst:dir:`graphviz`. -.. versionadded:: 1.1 - All three directives support a ``caption`` option that can be used to give a - caption to the diagram. + .. rst:directive:option:: alt: alternate text + :type: text -.. versionchanged:: 1.4 - All three directives support a ``graphviz_dot`` option that can be switch the - ``dot`` command within the directive. + .. versionadded:: 1.0 -.. versionadded:: 1.5 - All three directives support a ``align`` option to align the graph - horizontal. The values "left", "center", "right" are allowed. + .. rst:directive:option:: align: alignment of the graph + :type: left, center or right + + .. versionadded:: 1.5 + + .. rst:directive:option:: caption: caption of the graph + :type: text + + .. versionadded:: 1.1 + + .. rst:directive:option:: graphviz_dot: dot command of the graph + :type: text + + .. versionadded:: 1.4 + + .. rst:directive:option:: name: label + :type: text + + .. versionadded:: 1.6 -.. versionadded:: 1.6 - All three directives support a ``name`` option to set the label to graph. There are also these config values: From 290ead8ce7509374ad4c4dc4682b7cf59025bed8 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sun, 2 Jun 2019 19:59:41 +0900 Subject: [PATCH 3/6] Merge changes entry for 2.0.2 to 2.1.0 --- CHANGES | 22 ---------------------- 1 file changed, 22 deletions(-) diff --git a/CHANGES b/CHANGES index a3729db6c..77b365e17 100644 --- a/CHANGES +++ b/CHANGES @@ -138,28 +138,6 @@ Bugs fixed * #6408: html search: Fix the ranking of search results * #6406: Wrong year is returned for ``SOURCE_DATE_EPOCH`` * #6402: image directive crashes by unknown image format - -Testing --------- - -Release 2.0.2 (in development) -============================== - -Dependencies ------------- - -Incompatible changes --------------------- - -Deprecated ----------- - -Features added --------------- - -Bugs fixed ----------- - * #6286: C++, allow 8 and 9 in hexadecimal integer literals. * #6305: Fix the string in quickstart for 'path' argument of parser * LaTeX: Figures in admonitions produced errors (refs: #6364) From 653b0e00004c084aa154c72104d6451bdc7a6c42 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sun, 2 Jun 2019 21:10:40 +0900 Subject: [PATCH 4/6] Bump to 2.1.0 final --- CHANGES | 10 ++-------- sphinx/__init__.py | 4 ++-- 2 files changed, 4 insertions(+), 10 deletions(-) diff --git a/CHANGES b/CHANGES index 77b365e17..08759bb97 100644 --- a/CHANGES +++ b/CHANGES @@ -1,8 +1,5 @@ -Release 2.1.0 (in development) -============================== - -Dependencies ------------- +Release 2.1.0 (released Jun 02, 2019) +===================================== Incompatible changes -------------------- @@ -142,9 +139,6 @@ Bugs fixed * #6305: Fix the string in quickstart for 'path' argument of parser * LaTeX: Figures in admonitions produced errors (refs: #6364) -Testing --------- - Release 2.0.1 (released Apr 08, 2019) ===================================== diff --git a/sphinx/__init__.py b/sphinx/__init__.py index 0a6f26584..92faa78a3 100644 --- a/sphinx/__init__.py +++ b/sphinx/__init__.py @@ -32,7 +32,7 @@ if 'PYTHONWARNINGS' not in os.environ: warnings.filterwarnings('ignore', "'U' mode is deprecated", DeprecationWarning, module='docutils.io') -__version__ = '2.1.0+' +__version__ = '2.1.0' __released__ = '2.1.0' # used when Sphinx builds its own docs #: Version info for better programmatic use. @@ -43,7 +43,7 @@ __released__ = '2.1.0' # used when Sphinx builds its own docs #: #: .. versionadded:: 1.2 #: Before version 1.2, check the string ``sphinx.__version__``. -version_info = (2, 1, 0, 'beta', 0) +version_info = (2, 1, 0, 'final', 0) package_dir = path.abspath(path.dirname(__file__)) From 3360f2461c02ee4cfd351e1e3264edae55d1297a Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sun, 2 Jun 2019 21:14:52 +0900 Subject: [PATCH 5/6] Bump version --- CHANGES | 21 +++++++++++++++++++++ sphinx/__init__.py | 6 +++--- 2 files changed, 24 insertions(+), 3 deletions(-) diff --git a/CHANGES b/CHANGES index 08759bb97..b82a191ea 100644 --- a/CHANGES +++ b/CHANGES @@ -1,3 +1,24 @@ +Release 2.1.1 (in development) +============================== + +Dependencies +------------ + +Incompatible changes +-------------------- + +Deprecated +---------- + +Features added +-------------- + +Bugs fixed +---------- + +Testing +-------- + Release 2.1.0 (released Jun 02, 2019) ===================================== diff --git a/sphinx/__init__.py b/sphinx/__init__.py index 92faa78a3..8a6bdcc8b 100644 --- a/sphinx/__init__.py +++ b/sphinx/__init__.py @@ -32,8 +32,8 @@ if 'PYTHONWARNINGS' not in os.environ: warnings.filterwarnings('ignore', "'U' mode is deprecated", DeprecationWarning, module='docutils.io') -__version__ = '2.1.0' -__released__ = '2.1.0' # used when Sphinx builds its own docs +__version__ = '2.1.1+' +__released__ = '2.1.1' # used when Sphinx builds its own docs #: Version info for better programmatic use. #: @@ -43,7 +43,7 @@ __released__ = '2.1.0' # used when Sphinx builds its own docs #: #: .. versionadded:: 1.2 #: Before version 1.2, check the string ``sphinx.__version__``. -version_info = (2, 1, 0, 'final', 0) +version_info = (2, 1, 1, 'beta', 0) package_dir = path.abspath(path.dirname(__file__)) From bcc0ffbd18fcc4d5bbd5b18e94cd1e3ef50e6a26 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sun, 2 Jun 2019 21:16:14 +0900 Subject: [PATCH 6/6] Bump version --- CHANGES | 21 +++++++++++++++++++++ sphinx/__init__.py | 6 +++--- 2 files changed, 24 insertions(+), 3 deletions(-) diff --git a/CHANGES b/CHANGES index b82a191ea..07846fede 100644 --- a/CHANGES +++ b/CHANGES @@ -1,3 +1,24 @@ +Release 2.2.0 (in development) +============================== + +Dependencies +------------ + +Incompatible changes +-------------------- + +Deprecated +---------- + +Features added +-------------- + +Bugs fixed +---------- + +Testing +-------- + Release 2.1.1 (in development) ============================== diff --git a/sphinx/__init__.py b/sphinx/__init__.py index 8a6bdcc8b..57b3d6062 100644 --- a/sphinx/__init__.py +++ b/sphinx/__init__.py @@ -32,8 +32,8 @@ if 'PYTHONWARNINGS' not in os.environ: warnings.filterwarnings('ignore', "'U' mode is deprecated", DeprecationWarning, module='docutils.io') -__version__ = '2.1.1+' -__released__ = '2.1.1' # used when Sphinx builds its own docs +__version__ = '2.2.0+' +__released__ = '2.2.0' # used when Sphinx builds its own docs #: Version info for better programmatic use. #: @@ -43,7 +43,7 @@ __released__ = '2.1.1' # used when Sphinx builds its own docs #: #: .. versionadded:: 1.2 #: Before version 1.2, check the string ``sphinx.__version__``. -version_info = (2, 1, 1, 'beta', 0) +version_info = (2, 2, 0, 'beta', 0) package_dir = path.abspath(path.dirname(__file__))