From 36d03d1bac51f85eec92bb8cba0a0e91c36c83c8 Mon Sep 17 00:00:00 2001 From: Joel Pasvolsky Date: Fri, 18 Jul 2025 07:24:55 -0700 Subject: [PATCH 1/2] Restructure using the autosummary_class template --- .gitignore | 2 +- docs/_templates/autosummary_class.rst | 35 ++++++++++++++ docs/conf.py | 1 + docs/models.rst | 67 ++++++++++++++++++++------- docs/symbols.rst | 42 +---------------- 5 files changed, 87 insertions(+), 60 deletions(-) create mode 100644 docs/_templates/autosummary_class.rst diff --git a/.gitignore b/.gitignore index 4194f06e..d9ad7358 100644 --- a/.gitignore +++ b/.gitignore @@ -69,7 +69,7 @@ dwave/optimization/*.html # Sphinx documentation docs/_build/ -docs/reference/generated/ +docs/generated/ # meson-managed subprojects subprojects/ diff --git a/docs/_templates/autosummary_class.rst b/docs/_templates/autosummary_class.rst new file mode 100644 index 00000000..d5e472d5 --- /dev/null +++ b/docs/_templates/autosummary_class.rst @@ -0,0 +1,35 @@ +{{ objname | underline}} + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + :members: + :show-inheritance: + :inherited-members: + + {% block attributes %} + {% if attributes %} + {{ 'Properties' }} + {{ '----------' }} + + .. autosummary:: + {% for item in attributes %} + ~{{ name }}.{{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block methods %} + {% if methods %} + {{ 'Methods' }} + {{ '-------' }} + + .. autosummary:: + :signatures: none + {% for item in methods %} + {%- if not item.startswith('_') %} + ~{{ name }}.{{ item }} + {%- endif -%} + {%- endfor %} + {% endif %} + {% endblock %} \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index b5b03ecd..d2aefd8b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -27,6 +27,7 @@ ] autosummary_generate = True +templates_path = ['_templates'] source_suffix = ['.rst'] diff --git a/docs/models.rst b/docs/models.rst index c47bc224..a91a90b3 100644 --- a/docs/models.rst +++ b/docs/models.rst @@ -1,32 +1,63 @@ .. _optimization_models: -================ -Nonlinear Models -================ +========================================= +Nonlinear Models: Construction and States +========================================= -This page describes the `dwave-optimization` package's nonlinear model: classes, -attributes, and methods. +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 `_ +constituted of the package's :ref:`optimization_symbols` classes. For examples, see the :ref:`opt_index_examples_beginner` section. .. currentmodule:: dwave.optimization +Models and States +================= + .. automodule:: dwave.optimization.model -Model Class ------------ +.. autosummary:: + :recursive: + :nosignatures: + :toctree: generated + :template: autosummary_class.rst + + Model + States + +.. _optimization_symbols: + +Symbols +======= + +Symbols are a model's decision variables, intermediate variables, constants, +and mathematical operations. + +See the :ref:`Symbols ` section for an +introduction to working with symbols. + +All symbols inherit from the :class:`Symbol` class and therefore inherit its +methods. + +Most mathematical symbols inherit from the :class:`ArraySymbol` class and +therefore inherit its methods. + +All symbols listed on the :ref:`Model Symbols ` +page inherit from the :class:`Symbol` class and, for most +mathematical symbols, the :class:`ArraySymbol` class. -.. autoclass:: Model - :members: - :inherited-members: - :member-order: bysource +.. _symbols_base_symbols: -States Class ------------- +.. autosummary:: + :recursive: + :nosignatures: + :toctree: generated + :template: autosummary_class.rst -.. currentmodule:: dwave.optimization.states + Symbol + ArraySymbol -.. autoclass:: States - :members: - :inherited-members: - :member-order: bysource diff --git a/docs/symbols.rst b/docs/symbols.rst index 33f0ec65..4dc693a2 100644 --- a/docs/symbols.rst +++ b/docs/symbols.rst @@ -1,46 +1,6 @@ -.. _optimization_symbols: - -======= -Symbols -======= - -.. currentmodule:: dwave.optimization.model - -Symbols are a model's decision variables, intermediate variables, constants, -and mathematical operations. - -See the :ref:`Symbols ` section for an -introduction to working with symbols. - -All symbols listed in the :ref:`Model Symbols ` -subsection below inherit from the :class:`Symbol` class and, for most -mathematical symbols, the :class:`ArraySymbol` class. - -.. _symbols_base_symbols: - -Symbol -====== - -All symbols inherit from the :class:`Symbol` class and therefore inherit its -methods. - -.. autoclass:: Symbol - :members: - :member-order: bysource - -ArraySymbol -=========== - -Most mathematical symbols inherit from the :class:`ArraySymbol` class and -therefore inherit its methods. - -.. autoclass:: ArraySymbol - :members: - :show-inheritance: - :member-order: bysource - .. _symbols_model_symbols: +============= Model Symbols ============= From 266f9181a60e6c0a50322d9bf707338e52692046 Mon Sep 17 00:00:00 2001 From: Joel Pasvolsky Date: Thu, 24 Jul 2025 09:32:29 -0700 Subject: [PATCH 2/2] Restructure using the autosummary_module_* templates --- docs/_templates/autosummary_class.rst | 99 +++++++++++----- .../_templates/autosummary_module_classes.rst | 33 ++++++ .../autosummary_module_functions.rst | 33 ++++++ docs/api_ref.rst | 108 +++++++++++++++++- docs/generators.rst | 8 -- docs/math.rst | 10 -- docs/models.rst | 63 ---------- docs/symbols.rst | 17 --- 8 files changed, 238 insertions(+), 133 deletions(-) create mode 100644 docs/_templates/autosummary_module_classes.rst create mode 100644 docs/_templates/autosummary_module_functions.rst delete mode 100644 docs/generators.rst delete mode 100644 docs/math.rst delete mode 100644 docs/models.rst delete mode 100644 docs/symbols.rst diff --git a/docs/_templates/autosummary_class.rst b/docs/_templates/autosummary_class.rst index d5e472d5..5f1efaf3 100644 --- a/docs/_templates/autosummary_class.rst +++ b/docs/_templates/autosummary_class.rst @@ -2,34 +2,73 @@ .. currentmodule:: {{ module }} +{{ 'Class' }} +{{ '-----' }} + .. autoclass:: {{ objname }} - :members: - :show-inheritance: - :inherited-members: - - {% block attributes %} - {% if attributes %} - {{ 'Properties' }} - {{ '----------' }} - - .. autosummary:: - {% for item in attributes %} - ~{{ name }}.{{ item }} - {%- endfor %} - {% endif %} - {% endblock %} - - {% block methods %} - {% if methods %} - {{ 'Methods' }} - {{ '-------' }} - - .. autosummary:: - :signatures: none - {% for item in methods %} - {%- if not item.startswith('_') %} - ~{{ name }}.{{ item }} - {%- endif -%} - {%- endfor %} - {% endif %} - {% endblock %} \ No newline at end of file + +{# 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 %} \ No newline at end of file diff --git a/docs/_templates/autosummary_module_classes.rst b/docs/_templates/autosummary_module_classes.rst new file mode 100644 index 00000000..36e479bf --- /dev/null +++ b/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 %} \ No newline at end of file diff --git a/docs/_templates/autosummary_module_functions.rst b/docs/_templates/autosummary_module_functions.rst new file mode 100644 index 00000000..d17df16b --- /dev/null +++ b/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 %} \ No newline at end of file diff --git a/docs/api_ref.rst b/docs/api_ref.rst index 21ea5265..c5d64fcf 100644 --- a/docs/api_ref.rst +++ b/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 `_ +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 ` 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 ` +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 diff --git a/docs/generators.rst b/docs/generators.rst deleted file mode 100644 index 20fa4d4d..00000000 --- a/docs/generators.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. _optimization_generators: - -================ -Model Generators -================ - -.. automodule:: dwave.optimization.generators - :members: diff --git a/docs/math.rst b/docs/math.rst deleted file mode 100644 index 1e518dd0..00000000 --- a/docs/math.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _optimization_math: - -====================== -Mathematical Functions -====================== - -.. currentmodule:: dwave.optimization - -.. automodule:: dwave.optimization.mathematical - :members: diff --git a/docs/models.rst b/docs/models.rst deleted file mode 100644 index a91a90b3..00000000 --- a/docs/models.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. _optimization_models: - -========================================= -Nonlinear Models: Construction and States -========================================= - -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 `_ -constituted of the package's :ref:`optimization_symbols` classes. - -For examples, see the :ref:`opt_index_examples_beginner` section. - -.. currentmodule:: dwave.optimization - -Models and States -================= - -.. automodule:: dwave.optimization.model - -.. autosummary:: - :recursive: - :nosignatures: - :toctree: generated - :template: autosummary_class.rst - - Model - States - -.. _optimization_symbols: - -Symbols -======= - -Symbols are a model's decision variables, intermediate variables, constants, -and mathematical operations. - -See the :ref:`Symbols ` section for an -introduction to working with symbols. - -All symbols inherit from the :class:`Symbol` class and therefore inherit its -methods. - -Most mathematical symbols inherit from the :class:`ArraySymbol` class and -therefore inherit its methods. - -All symbols listed on the :ref:`Model Symbols ` -page inherit from the :class:`Symbol` class and, for most -mathematical symbols, the :class:`ArraySymbol` class. - -.. _symbols_base_symbols: - -.. autosummary:: - :recursive: - :nosignatures: - :toctree: generated - :template: autosummary_class.rst - - Symbol - ArraySymbol - diff --git a/docs/symbols.rst b/docs/symbols.rst deleted file mode 100644 index 4dc693a2..00000000 --- a/docs/symbols.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. _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. - -.. automodule:: dwave.optimization.symbols - :members: - :show-inheritance: