Merge pull request #3389 from jsiirola/doc-autoenum

Improved autoenum documentation

.readthedocs.yaml

@@ -8,7 +8,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.8"
+    python: "3.11"
 
 sphinx:
    configuration: doc/OnlineDocs/conf.py

doc/OnlineDocs/_templates/recursive-class.rst

@@ -13,7 +13,7 @@
 {# Note that numpy.ndarray examples fail doctest; disable documentation
    of inherited members for classes derived from ndarray #}
 
-.. autoclass:: {{ objname }}
+.. autoclass:: {{ module }}::{{ objname }}
    :members:
    :show-inheritance:
    {{ '' if (module + '.' + name) in (
@@ -45,3 +45,5 @@
    {%- endfor %}
    {% endif %}
    {% endblock %}
+
+   .. rubric:: Member Documentation

doc/OnlineDocs/_templates/recursive-enum.rst

@@ -0,0 +1,54 @@
+{{ name | escape | underline}}
+
+(enum from :py:mod:`{{ module }}`)
+
+.. testsetup:: *
+
+   # import everything from the module containing this class so that
+   # doctests for the class docstrings see the correct environment
+   from {{ module }} import *
+
+.. currentmodule:: {{ module }}
+
+.. autoenum:: {{ module }}::{{ objname }}
+   :members:
+   :inherited-members:
+   :undoc-members:
+   :show-inheritance:
+
+   {% block enum_members %}
+   {% if enum_members %}
+   .. rubric:: {{ _('Enum Members') }}
+
+   {{ member_type }}
+
+   .. autosummary::
+      {% for item in enum_members %}
+      ~{{ name }}.{{ item }}
+      {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+      {% for item in methods %}
+      ~{{ name }}.{{ item }}
+      {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+      {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+      {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   .. rubric:: Member Documentation

doc/OnlineDocs/_templates/recursive-module.rst

@@ -21,14 +21,14 @@ Library Reference
    {% endif %}
    {%- endblock %}
 
-   {%- block functions %}
-   {%- if functions %}
-   .. rubric:: {{ _('Functions') }}
+   {% block enums %}
+   {%- if enums %}
+   .. rubric:: {{ _('Enums') }}
 
    .. autosummary::
       :toctree:
-      :template: recursive-base.rst
-   {% for item in functions %}
+      :template: recursive-enum.rst
+   {% for item in enums %}
       {{ item }}
    {%- endfor %}
    {% endif %}
@@ -60,6 +60,19 @@ Library Reference
    {% endif %}
    {%- endblock %}
 
+   {%- block functions %}
+   {%- if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree:
+      :template: recursive-base.rst
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {%- endblock %}
+
 {%- block modules %}
 {%- if modules %}
 .. rubric:: Modules

doc/OnlineDocs/conf.py

@@ -35,6 +35,8 @@
 sys.path.insert(0, os.path.abspath('../../../pyutilib'))
 # top-level pyomo source directory
 sys.path.insert(0, os.path.abspath('../..'))
+# our sphinx extensions
+sys.path.insert(0, os.path.abspath('ext'))
 
 # -- Rebuild SPY files ----------------------------------------------------
 sys.path.insert(0, os.path.abspath('src'))
@@ -71,18 +73,17 @@
 # ones.
 extensions = [
     'sphinx.ext.intersphinx',
-    'sphinx.ext.autodoc',
     'sphinx.ext.coverage',
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
     'sphinx.ext.napoleon',
-    'sphinx.ext.ifconfig',
     'sphinx.ext.inheritance_diagram',
-    'sphinx.ext.autosummary',
     'sphinx.ext.doctest',
     'sphinx.ext.todo',
     'sphinx_copybutton',
-    'enum_tools.autoenum',
+    # Our version of 'autoenum', designed to work with autosummary.
+    # This adds 'sphinx.ext.autosummary', and 'sphinx.ext.autodoc':
+    'pyomo_autosummary_autoenum',
 ]
 
 viewcode_follow_imported_members = True
@@ -244,7 +245,7 @@
 ]
 
 # autodoc_member_order = 'bysource'
-# autodoc_member_order = 'groupwise'
+autodoc_member_order = 'groupwise'
 
 autosummary_generate = True
 autosummary_ignore_module_all = True