diff --git a/CHANGES b/CHANGES index 0c5b23d8c..c980568e5 100644 --- a/CHANGES +++ b/CHANGES @@ -21,7 +21,7 @@ Bugs fixed Testing -------- -Release 2.1.0 (in development) +Release 2.2.0 (in development) ============================== Dependencies @@ -30,6 +30,45 @@ Dependencies Incompatible changes -------------------- +Deprecated +---------- + +Features added +-------------- + +Bugs fixed +---------- + +Testing +-------- + +Release 2.1.1 (in development) +============================== + +Dependencies +------------ + +Incompatible changes +-------------------- + +Deprecated +---------- + +Features added +-------------- + +Bugs fixed +---------- + +Testing +-------- + +Release 2.1.0 (released Jun 02, 2019) +===================================== + +Incompatible changes +-------------------- + * Ignore filenames without file extension given to ``Builder.build_specific()`` API directly * #6230: The anchor of term in glossary directive is changed if it is consisted @@ -115,6 +154,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 '.' @@ -161,35 +202,10 @@ 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) -Testing --------- - Release 2.0.1 (released Apr 08, 2019) ===================================== 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: diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py index 07bf54e10..ed7090b6c 100644 --- a/sphinx/ext/autodoc/__init__.py +++ b/sphinx/ext/autodoc/__init__.py @@ -547,8 +547,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: @@ -578,12 +580,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 @@ -592,6 +595,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 @@ -1289,6 +1294,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 f60b2bb0b..4d893ba42 100644 --- a/tests/test_autodoc.py +++ b/tests/test_autodoc.py @@ -1686,6 +1686,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"