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..5f1efaf3 --- /dev/null +++ b/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 %} \ 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/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/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 c47bc224..00000000 --- a/docs/models.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. _optimization_models: - -================ -Nonlinear Models -================ - -This page describes the `dwave-optimization` package's nonlinear model: classes, -attributes, and methods. - -For examples, see the :ref:`opt_index_examples_beginner` section. - -.. currentmodule:: dwave.optimization - -.. automodule:: dwave.optimization.model - -Model Class ------------ - -.. autoclass:: Model - :members: - :inherited-members: - :member-order: bysource - -States Class ------------- - -.. currentmodule:: dwave.optimization.states - -.. autoclass:: States - :members: - :inherited-members: - :member-order: bysource diff --git a/docs/symbols.rst b/docs/symbols.rst deleted file mode 100644 index 33f0ec65..00000000 --- a/docs/symbols.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. _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 -============= - -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: