Automate autosummary documentation (WIP)

.gitignore

@@ -69,7 +69,7 @@ dwave/optimization/*.html
 
 # Sphinx documentation
 docs/_build/
-docs/reference/generated/
+docs/generated/
 
 # meson-managed subprojects
 subprojects/

docs/_templates/autosummary_class.rst

@@ -0,0 +1,74 @@
+{{ objname | underline}}
+
+.. currentmodule:: {{ module }}
+
+{{ 'Class' }}
+{{ '-----' }}
+
+.. autoclass:: {{ objname }}
+
+{# Aesthetic section: drop if maintenance becomes a future difficulty #}
+{% set counter_methods = namespace(count = 0) %}
+{% for item in methods %}
+    {%- if not item.startswith('_') %}
+        {% set counter_methods.count = counter_methods.count + 1 %}
+    {%- endif -%}
+{%- endfor %}
+
+{% if attributes or counter_methods.count > 0 %}
+    {{- 'Class Members: Summary\n' }}
+    {{- '----------------------'}}
+{% endif %}
+
+{% block attributes %}
+{% if attributes %}
+    {{- 'Properties\n' }}
+    {{- '~~~~~~~~~~\n' }}
+    {{- '.. autosummary::' }}
+    {% for item in attributes %}
+        ~{{ name }}.{{ item }}
+    {% endfor %}
+{% endif %}
+{% endblock %}
+
+{% block methods %}
+{% if counter_methods.count > 0 %}
+    {{- 'Methods\n' }}
+    {{- '~~~~~~~\n' }}
+    {{- '.. autosummary::' }}
+    {{- '    :nosignatures:'}}
+    {% for item in methods %}
+        {%- if not item.startswith('_') %}
+            ~{{ name }}.{{ item }}
+        {%- endif -%}
+    {% endfor %}
+{% endif %}
+{% endblock %}
+
+{% if attributes or counter_methods.count > 0 %}
+    {{- 'Class Members: Descriptions\n' }}
+    {{- '---------------------------' }}
+{% endif %}
+
+
+{% block attributes2 %}
+{% if attributes %}
+    {{- 'Properties\n' }}
+    {{- '~~~~~~~~~~\n' }}
+    {% for item in attributes %}
+.. autoattribute:: {{ name }}.{{ item }}
+    {%- endfor %}
+{% endif %}
+{% endblock %}
+
+{% block methods2 %}
+{% if counter_methods.count > 0 %}
+    {{- 'Methods\n' }}
+    {{- '~~~~~~~\n' }}
+    {% for item in methods %}
+        {%- if not item.startswith('_') %}
+.. automethod:: {{ name }}.{{ item }}
+        {%- endif -%}
+    {% endfor %}
+{% endif %}
+{% endblock %}

docs/_templates/autosummary_module_classes.rst

@@ -0,0 +1,33 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+{{ 'Classes: Summary' }}
+{{ '----------------' }}
+
+{% block classes %}
+{# To prevent template error, but template should not be applied to such modules #}
+{% if classes %}
+   {{- '.. autosummary::' }}
+   {%- for item in classes %}
+      {%- if not item.startswith('_') %}
+      {{ item }}
+      {%- endif %}
+   {%- endfor %}
+{% endif %}
+{% endblock %}
+
+
+{{ 'Classes: Descriptions'}}
+{{ '---------------------' }}
+
+{% block classes2 %}
+{# To prevent template error, but template should not be applied to such modules #}
+{% if classes %}
+   {%- for item in classes %}
+      {%- if not item.startswith('_') %}
+.. autoclass:: {{ item }}
+      {%- endif %}
+   {%- endfor %}
+{% endif %}
+{% endblock %}

docs/_templates/autosummary_module_functions.rst

@@ -0,0 +1,33 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+{{ 'Functions: Summary' }}
+{{ '------------------' }}
+
+{% block functions %}
+{# To prevent template error, but template should not be applied to such modules #}
+{% if functions %}
+   {{- '.. autosummary::' }}
+   {%- for item in functions %}
+      {%- if not item.startswith('_') %}
+      {{ item }}
+      {%- endif %}
+   {%- endfor %}
+{% endif %}
+{% endblock %}
+
+
+{{ 'Functions: Descriptions'}}
+{{ '-----------------------' }}
+
+{% block functions2 %}
+{# To prevent template error, but template should not be applied to such modules #}
+{% if functions %}
+   {%- for item in functions %}
+      {%- if not item.startswith('_') %}
+.. autofunction:: {{ item }}
+      {%- endif %}
+   {%- endfor %}
+{% endif %}
+{% endblock %}

docs/api_ref.rst

@@ -4,10 +4,108 @@
 API Reference
 =============
 
-.. toctree::
-    :maxdepth: 2
+Nonlinear Models
+================
+
+The `dwave-optimization` package provides the
+:class:`~dwave.optimization.model.Model` and
+:class:`~dwave.optimization.model.States` classes to construct nonlinear models
+and handle results, respectively. These models map to a
+`directed acyclic graph <https://en.wikipedia.org/wiki/Directed_acyclic_graph>`_
+constituted of the package's :ref:`optimization_symbols` classes.
+
+For examples, see the :ref:`opt_index_examples_beginner` section.
+
+Models and States
+-----------------
+
+.. automodule:: dwave.optimization.model
+
+.. currentmodule:: dwave.optimization
+
+.. autosummary::
+    :recursive:
+    :nosignatures:
+    :toctree: generated
+    :template: autosummary_class.rst
+
+    ~model.Model
+    ~model.States
+
+.. _optimization_generators:
+
+Model Generators
+~~~~~~~~~~~~~~~~
+
+.. autosummary::
+   :recursive:
+   :toctree: generated/
+   :template: autosummary_module_functions.rst
+
+   generators
+
+.. _optimization_math:
+
+Mathematical Functions
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. autosummary::
+   :recursive:
+   :toctree: generated/
+   :template: autosummary_module_functions.rst
+
+   mathematical
+
+.. _optimization_symbols:
+
+Symbols
+-------
+
+Symbols are a model's decision variables, intermediate variables, constants,
+and mathematical operations.
+
+See the :ref:`Symbols <opt_model_construction_nl_symbols>` section for an
+introduction to working with symbols.
+
+All symbols inherit from the :class:`~dwave.optimization.model.Symbol` class and
+therefore inherit its methods.
+
+Most mathematical symbols inherit from the
+:class:`~dwave.optimization.model.ArraySymbol` class and therefore inherit its
+methods.
+
+All symbols listed on the :ref:`Model Symbols <symbols_model_symbols>`
+page inherit from the :class:`~dwave.optimization.model.Symbol` class and, for
+most mathematical symbols, the :class:`~dwave.optimization.model.ArraySymbol`
+class.
+
+.. _symbols_base_symbols:
+
+.. autosummary::
+    :recursive:
+    :nosignatures:
+    :toctree: generated
+    :template: autosummary_class.rst
+
+    ~model.Symbol
+    ~model.ArraySymbol
+
+.. _symbols_model_symbols:
+
+Model Symbols
+~~~~~~~~~~~~~
+
+Each operation, decision, constant, mathematical function, and
+flow control is modeled using a symbol. The following symbols
+are available for modelling.
+
+In general, symbols should be created using the methods inherited from
+:class:`Symbol` and :class:`ArraySymbol`, rather than by the constructors
+of the following classes.
+
+.. autosummary::
+   :recursive:
+   :toctree: generated/
+   :template: autosummary_module_classes.rst
 
-    models
-    generators
-    math
     symbols

docs/conf.py

@@ -27,6 +27,7 @@
 ]
 
 autosummary_generate = True
+templates_path = ['_templates']
 
 source_suffix = ['.rst']