Docs CI fixes (Qiskit#402)

* Docs CI fixes

This commit makes 2 changes to the docs ci configuration. The first
fixes a bash syntax issue in the deploy script which was blocking the
publishing of stable versions of the docs on release. With that typo
fixed we won't manually need to reupload documentation to the stable
path on release. The second fix is a future facing fix for reno, since
we switched to using main as the default branch if we ever introduced a
stable branch to retworkx a bug in reno<3.4.0 would require a master
branch to exist. This commit bumps the minimum reno version to 3.4.0 and
configures it to use main as the default branch in case we ever start
using stable branches.

* Update docs configuration

This commit tweaks the sphinx configuration to remove all the comments
leftover from the config generator and also update the autdoc configuration
and templates to simplify the build slightly.

docs/source/_templates/autosummary/class.rst

@@ -1,49 +1,41 @@
-{% if referencefile %}
-.. include:: {{ referencefile }}
-{% endif %}
+{#
+   The general principle of this is that we manually document attributes here in
+   the same file, but give all methods their own page.  By default, we document
+   all methods, including those defined by parent classes.
+-#}
 
-{{ objname }}
-{{ underline }}
+{{ objname | escape | underline }}
 
 .. currentmodule:: {{ module }}
 
 .. autoclass:: {{ objname }}
+{#-
+   Avoid having autodoc populate the class with the members we're about to
+   summarize to avoid duplication.
+#}
    :no-members:
-   :no-inherited-members:
-   :no-special-members:
-
-   {% block attributes_summary %}
-   {% if attributes %}
-
-   .. rubric:: Attributes
-
-   .. autosummary::
-      :toctree: ../stubs/
-   {% for item in all_attributes %}
-      {%- if not item.startswith('_') %}
-      {{ name }}.{{ item }}
-      {%- endif -%}
-   {%- endfor %}
-   {% endif %}
-   {% endblock %}
-
-   {% block methods_summary %}
-   {% if methods %}
-
+   :show-inheritance:
+{#
+   Methods all get their own separate page, with their names and the first lines
+   of their docstrings tabulated.  The documentation from `__init__` is
+   automatically included in the standard class documentation, so we don't want
+   to repeat it.
+-#}
+{% block methods_summary %}{% set wanted_methods = (methods | reject('==', '__init__') | list) %}{% if wanted_methods %}
    .. rubric:: Methods
 
    .. autosummary::
+      :nosignatures:
       :toctree: ../stubs/
-   {% for item in all_methods %}
-      {%- if not item.startswith('_') or item in ['__call__', '__mul__', '__getitem__', '__len__'] %}
-      {{ name }}.{{ item }}
-      {%- endif -%}
-   {%- endfor %}
-   {% for item in inherited_members %}
-      {%- if item in ['__call__', '__mul__', '__getitem__', '__len__'] %}
-      {{ name }}.{{ item }}
-      {%- endif -%}
-   {%- endfor %}
+{% for item in wanted_methods %}
+      ~{{ name }}.{{ item }}
+{%- endfor %}
+{% endif %}{% endblock %}
 
-   {% endif %}
-   {% endblock %}
+{% block attributes_summary %}{% if attributes %}
+   .. rubric:: Attributes
+{# Attributes should all be summarized directly on the same page. -#}
+{% for item in attributes %}
+   .. autoattribute:: {{ item }}
+{%- endfor %}
+{% endif %}{% endblock -%}