Fix automatic documenting of class methods via autosummary (#5021)

* WIP: Autogenerate stubs for class methods.

Modify default autosummary/classes template to auto-generate
method stubs.

* WIP: preserve special-casing of __init__.

__init__ method of classes is embedded in main class doc and thus
should be ignored in method autosummary.

* Suppress sphinx warnings.
 * Remove manual autosummary of ismags methods
 * Escape some rst characters in argmap.signature docstring.

3 files changed, 41 insertions, 11 deletions

diff --git a/doc/_templates/autosummary/class.rst b/doc/_templates/autosummary/class.rst
new file mode 100644
index 00000000..0d585a1c
--- /dev/null
+++ b/doc/_templates/autosummary/class.rst
@@ -0,0 +1,35 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+   {% block methods %}
+   .. automethod:: __init__
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+      :toctree: generated/
+
+   {% for item in methods %}
+       {% if item != "__init__" %}
+          ~{{ name }}.{{ item }}
+       {% endif %}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+      :toctree: generated/
+
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
diff --git a/doc/reference/algorithms/isomorphism.ismags.rst b/doc/reference/algorithms/isomorphism.ismags.rst
index 8ca55fae..d9d19cae 100644
--- a/doc/reference/algorithms/isomorphism.ismags.rst
+++ b/doc/reference/algorithms/isomorphism.ismags.rst
@@ -11,13 +11,6 @@ ISMAGS object
 .. currentmodule:: networkx.algorithms.isomorphism
 
 .. autosummary::
-    :toctree: generated/
-
-     ISMAGS
-     ISMAGS.analyze_symmetry
-     ISMAGS.is_isomorphic
-     ISMAGS.subgraph_is_isomorphic
-     ISMAGS.isomorphisms_iter
-     ISMAGS.subgraph_isomorphisms_iter
-     ISMAGS.largest_common_subgraph
+   :toctree: generated/
 
+   ISMAGS
diff --git a/networkx/utils/decorators.py b/networkx/utils/decorators.py
index f615bb04..a9dc032a 100644
--- a/networkx/utils/decorators.py
+++ b/networkx/utils/decorators.py
@@ -1076,6 +1076,8 @@ class argmap:
         sig : argmap.Signature
             The Signature of f
 
+        Notes
+        -----
         The Signature is a namedtuple with names:
 
             name : a unique version of the name of the decorated function
@@ -1084,8 +1086,8 @@ class argmap:
             call_sig : a string used as code to call the decorated function
             names : a dict keyed by argument name and index to the argument's name
             n_positional : the number of positional arguments in the signature
-            args : the name of the VAR_POSITIONAL argument if any, i.e. *theseargs
-            kwargs : the name of the VAR_KEYWORDS argument if any, i.e. **kwargs
+            args : the name of the VAR_POSITIONAL argument if any, i.e. \*theseargs
+            kwargs : the name of the VAR_KEYWORDS argument if any, i.e. \*\*kwargs
 
         These named attributes of the signature are used in `assemble` and `compile`
         to construct a string of source code for the decorated function.