Merge pull request #1400 from JoelPasvolsky/unifieddocs

Restructure and update references for unified documentation

Author: arcondello

.circleci/config.yml

@@ -231,13 +231,6 @@ jobs:
           command: |
             . env/bin/activate
             make -C docs/ linkcheck
-      - run:
-          # If we add more notebooks in the future we can make this more general.
-          # We avoid a (slow) dimod install by playing around with the path.
-          name: test scaling guide
-          command: |
-            . env/bin/activate
-            PYTHONPATH=$(pwd):$PYTHONPATH jupyter nbconvert --to notebook --execute docs/intro/intro_scaling.ipynb
 
   test-linux:
     parameters:

.gitignore

@@ -63,10 +63,11 @@ instance/
 
 # Sphinx documentation
 docs/build/
+docs/_build/
 docs/build-cpp/
-docs/reference/generated/
+docs/generated/
 docs/intro/generated/
-docs/reference/*/generated/
+docs/*/generated/
 
 # PyBuilder
 target/

README.rst

@@ -10,29 +10,20 @@
 .. image:: https://codecov.io/gh/dwavesystems/dimod/branch/main/graph/badge.svg
     :target: https://codecov.io/gh/dwavesystems/dimod
 
+=====
 dimod
 =====
 
-.. index-start-marker1
+.. start_dimod_about
 
 `dimod` is a shared API for samplers. It provides:
 
-* classes for quadratic models---such as the binary quadratic model (BQM) class that
-  contains Ising and QUBO models used by samplers such as the D-Wave system---and
-  higher-order (non-quadratic) models.
-* reference examples of samplers and composed samplers.
-* `abstract base classes <https://docs.python.org/3/library/abc.html>`_ for
-  constructing new samplers and composed samplers.
-
-.. index-end-marker1
-
-(For explanations of the terminology, see the
-`Ocean glossary <https://docs.ocean.dwavesys.com/en/stable/concepts/index.html>`_.)
-
-Example Usage
--------------
-
-.. index-start-marker2
+*   Classes for quadratic models---such as the binary quadratic model (BQM)
+    class that contains Ising and QUBO models used by samplers such as the
+    D-Wave quantum computer---and higher-order (non-quadratic) models.
+*   Reference examples of samplers and composed samplers.
+*   `Abstract base classes <https://docs.python.org/3/library/abc.html>`_ for
+    constructing new samplers and composed samplers.
 
 >>> import dimod
 ...
@@ -49,40 +40,40 @@ Example Usage
 2  1  1    2.0       1
 ['BINARY', 4 rows, 4 samples, 2 variables]
 
-.. index-end-marker2
+.. end_dimod_about
+
+For explanations of the terminology, see the
+`Ocean glossary <https://docs.dwavequantum.com/en/latest/concepts/index.html>`_.
 
-See the `documentation <https://docs.ocean.dwavesys.com/en/stable/docs_dimod/>`_
+See the `documentation <https://docs.dwavequantum.com/en/latest/index.html>`_
 for more examples.
 
 Installation
-------------
-
-.. installation-start-marker
+============
 
 Installation from `PyPI <https://pypi.org/project/dimod>`_:
 
 .. code-block:: bash
 
     pip install dimod
 
-.. installation-end-marker
-
 License
--------
+=======
 
 Released under the Apache License 2.0. See LICENSE file.
 
 Contributing
-------------
+============
 
-Ocean's `contributing guide <https://docs.ocean.dwavesys.com/en/stable/contributing.html>`_
-has guidelines for contributing to Ocean packages.
+Ocean's
+`contributing <https://docs.dwavequantum.com/en/latest/ocean/contribute.html>`_
+section has guidelines for contributing to Ocean packages.
 
 dimod includes some formatting customization in the
 `.clang-format <.clang-format>`_ and `setup.cfg <setup.cfg>`_ files.
 
 Release Notes
-~~~~~~~~~~~~~
+-------------
 
 dimod makes use of `reno <https://docs.openstack.org/reno/>`_ to manage its
 release notes.
@@ -98,5 +89,6 @@ You can then edit the file created under ``releasenotes/notes/``.
 Remove any sections not relevant to your changes.
 Commit the file along with your changes.
 
-See reno's `user guide <https://docs.openstack.org/reno/latest/user/usage.html>`_
-for details.
+See reno's
+`user guide <https://docs.openstack.org/reno/latest/user/usage.html>`_ for
+details.

dimod/binary/binary_quadratic_model.py

@@ -577,8 +577,8 @@ def spin(self) -> 'BinaryQuadraticModel':
             This example exploits the simplicity of the Ising representation of
             a Boolean NOT gate, :math:`s_1s_2`, relative to its QUBO counterpart,
             :math:`2x_1x_2−x_1−x_2+1`, to change a QUBO representation of an AND
-            gate, derived in the :std:doc:`Ocean documentation's <oceandocs:index>`
-            :ref:`AND example <oceandocs:and>`, to represent a NAND gate.
+            gate, derived in the :ref:`AND example <qpu_example_and>`, to
+            represent a NAND gate.
 
             >>> Q = [[0, 1, -2], [0, 0, -2], [0, 0, 3]]
             >>> x = dimod.BinaryArray(["in1", "in2", "out_and"])
@@ -1135,7 +1135,7 @@ def maximum_energy_delta(self) -> Bias:
         result from flipping a single variable in a binary quadratic model.
 
         The bound is useful as a starting point for determining the values of
-        `penalty parameters`_ in a `penalty model`_.
+        `penalty parameters`_ in a :ref:`penalty model <concept_penalty>`.
 
         Returns:
             Bound on change in energy.
@@ -1147,8 +1147,6 @@ def maximum_energy_delta(self) -> Bias:
             5.5
 
         .. _`penalty parameters`: https://en.wikipedia.org/wiki/Penalty_method
-        .. _`penalty model`: https://docs.ocean.dwavesys.com/en/stable/concepts/index.html#term-Penalty-model
-
         """
         if not self.num_variables:
             return 0
@@ -2656,11 +2654,11 @@ def Binaries(labels: Union[int, Iterable[Variable]],
 
     Examples:
         This example generates a BQM that represents a Boolean NOT gate as a
-        penalty model, :math:`2xy - x - y`, described in
-        :std:doc:`Ocean documentation's <oceandocs:index>`
-        :ref:`NOT example <oceandocs:not>`. The output of the brute-force solver,
-        :class:`~dimod.reference.samplers.ExactSolver`, shows that best
-        solutions are for assignments of the variables where :math:`z = \overline{x}`.
+        penalty model, :math:`2xy - x - y`, described in the
+        :ref:`NOT example <qpu_example_not>` section. The output of the
+        brute-force solver, :class:`~dimod.reference.samplers.ExactSolver`,
+        shows that best solutions are for assignments of the variables where
+        :math:`z = \overline{x}`.
 
         >>> x, y = dimod.Binaries(["x", "y"])
         >>> bqm = 2*x*y - x - y
@@ -2704,8 +2702,7 @@ def BinaryArray(labels: Union[int, Iterable[Variable]],
                     0 & 0 & 3
                  \\end{bmatrix},
 
-        derived in the :std:doc:`Ocean documentation's <oceandocs:index>`
-        :ref:`AND example <oceandocs:and>`.
+        derived in the :ref:`AND example <qpu_example_and>` section.
 
         >>> Q = [[0, 1, -2], [0, 0, -2], [0, 0, 3]]
         >>> x = dimod.BinaryArray(["in1", "in2", "out"])
@@ -2758,8 +2755,7 @@ def Spins(labels: Union[int, Iterable[Variable]],
     Examples:
         This example generates a BQM that represents the constraint :math:`s_1 = s_2`
         as a penalty model, :math:`-\\frac{1}{2}s_1s_2`, described in the
-        :std:doc:`system documentation's <sysdocs_gettingstarted:index>`
-        :std:doc:`sysdocs_gettingstarted:doc_getting_started` guide.
+        :ref:`concept_penalty` section.
         The output of the brute-force solver,
         :class:`~dimod.reference.samplers.ExactSolver`, shows that best
         solutions are for eqaul assignments of the variables' values.

dimod/constrained/constrained.py

@@ -286,7 +286,7 @@ def add_constraint_from_comparison(self,
         r"""Add a constraint from a symbolic comparison.
 
         For a more detailed discussion of symbolic model manipulation, see
-        :ref:`intro_symbolic_math`.
+        the :ref:`concept_symbolic_math` section.
 
         Args:
             comp: Comparison object, generally constructed using symbolic math.

dimod/core/composite.py

@@ -42,8 +42,8 @@
     >>> set(sampleset.first.sample.values()) == {-1}
     True
 
-    For more examples, see the source code for the composed
-    documented in :ref:`quadratic_composites`.
+    For more examples, see the source code for the composed samplers
+    documented in the :ref:`dimod_composites` section.
 """
 import abc
 

docs/LICENSE

@@ -0,0 +1,20 @@
+.. _dimod_api_ref:
+
+=============
+API Reference
+=============
+
+.. toctree::
+    :maxdepth: 2
+
+    models
+    generators
+    utilities
+    sampleset
+    vartypes
+    sampler_composites
+    api_samplers_composites
+    variables
+    exceptions
+    typing
+    cpp