Merge with master and address code review

3 files changed, 119 insertions, 23 deletions

diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst
index 8fdee214b..74c0b609d 100644
--- a/doc/usage/extensions/autodoc.rst
+++ b/doc/usage/extensions/autodoc.rst
@@ -243,21 +243,23 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
    These work exactly like :rst:dir:`autoclass` etc.,
    but do not offer the options used for automatic member documentation.
 
-   :rst:dir:`autodata` and :rst:dir:`autoattribute` support
-   the ``annotation`` option.
-   Without this option, the representation of the object
-   will be shown in the documentation.
-   When the option is given without arguments,
-   only the name of the object will be printed::
+   :rst:dir:`autodata` and :rst:dir:`autoattribute` support the ``annotation``
+   option.  The option controls how the value of variable is shown.  If specified
+   without arguments, only the name of the variable will be printed, and its value
+   is not shown::
 
       .. autodata:: CD_DRIVE
          :annotation:
 
-   You can tell sphinx what should be printed after the name::
+   If the option specified with arguments, it is printed after the name as a value
+   of the variable::
 
       .. autodata:: CD_DRIVE
          :annotation: = your CD device name
 
+   By default, without ``annotation`` option, Sphinx tries to obtain the value of
+   the variable and print it after the name.
+
    For module data members and class attributes, documentation can either be put
    into a comment with special formatting (using a ``#:`` to start the comment
    instead of just ``#``), or in a docstring *after* the definition.  Comments
diff --git a/doc/usage/extensions/autosummary.rst b/doc/usage/extensions/autosummary.rst
index 316ffcb9d..59620b4a8 100644
--- a/doc/usage/extensions/autosummary.rst
+++ b/doc/usage/extensions/autosummary.rst
@@ -148,12 +148,19 @@ also use these config values:
    The new files will be placed in the directories specified in the
    ``:toctree:`` options of the directives.
 
+.. confval:: autosummary_generate_overwrite
+
+   If true, autosummary already overwrites stub files by generated contents.
+   Defaults to true (enabled).
+
+   .. versionadded:: 3.0
+
 .. confval:: autosummary_recursive
 
    Boolean that determines whether to add modules and sub-packages
    recursively. It is disabled by default.
 
-   .. versionadded:: 2.2
+   .. versionadded:: 3.0
 
 .. confval:: autosummary_mock_imports
 
diff --git a/doc/usage/extensions/graphviz.rst b/doc/usage/extensions/graphviz.rst
index 4d801d346..dd21b8214 100644
--- a/doc/usage/extensions/graphviz.rst
+++ b/doc/usage/extensions/graphviz.rst
@@ -39,6 +39,49 @@ 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:: layout: layout type of the graph
+      :type: text
+
+      The layout of the graph (ex. ``dot``, ``neato`` and so on).  A path to the
+      graphviz commands are also allowed.  By default, :confval:`graphviz_dot`
+      is used.
+
+      .. versionadded:: 1.4
+      .. versionchanged:: 2.2
+
+         Renamed from ``graphviz_dot``
+
+   .. rst:directive:option:: name: label
+      :type: text
+
+      The label of the graph.
+
+      .. versionadded:: 1.6
+
 
 .. rst:directive:: graph
 
@@ -56,6 +99,38 @@ 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:: layout: layout type of the graph
+      :type: text
+
+      .. versionadded:: 1.4
+      .. versionchanged:: 2.2
+
+         Renamed from ``graphviz_dot``
+
+   .. rst:directive:option:: name: label
+      :type: text
+
+      .. versionadded:: 1.6
+
 
 .. rst:directive:: digraph
 
@@ -69,26 +144,38 @@ It adds these directives:
 
          "bar" -> "baz" -> "quux";
 
+   .. 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:: layout: layout type of the graph
+      :type: text
 
-.. 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.
+      .. versionadded:: 1.4
+      .. versionchanged:: 2.2
 
-.. versionadded:: 1.1
-   All three directives support a ``caption`` option that can be used to give a
-   caption to the diagram.
+         Renamed from ``graphviz_dot``
 
-.. versionchanged:: 1.4
-   All three directives support a ``graphviz_dot`` option that can be switch the
-   ``dot`` command within the directive.
+   .. rst:directive:option:: name: label
+      :type: text
 
-.. versionadded:: 1.5
-   All three directives support a ``align`` option to align the graph
-   horizontal.  The values "left", "center", "right" are allowed.
+      .. 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: