Add doctests in CI

.circleci/config.yml

@@ -220,6 +220,36 @@ jobs:
           command: |
             FLAGS=-Werror make -C tests/cpp/
 
+  docs:
+    docker:
+      - image: cimg/python:3.10  # As of July 2024, RTD uses 3.10
+
+    steps:
+      - checkout
+      - attach_workspace:
+          at: dist
+      - run:
+          name: install package and docs dependencies
+          command: |
+            python -m venv env
+            . env/bin/activate
+            pip install dist/*optimization*cp310*.whl -r docs/requirements.txt
+
+      - run:
+          name: build docs
+          command: |
+            . env/bin/activate
+            make -C docs html
+
+      - store_artifacts:
+          path: docs/build/html
+
+      - run:
+          name: doctest
+          command: |
+            . env/bin/activate
+            make -C docs doctest
+
   deploy:
     docker:
       - image: cimg/python:3.9
@@ -282,6 +312,9 @@ workflows:
             - python-linux
       - cpp-linux
       - cpp-macOS
+      - docs:
+          requires:
+            - python-linux
       - deploy:
           filters:
             tags:

docs/conf.py

@@ -5,14 +5,6 @@
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-#
-import os
-import subprocess
-import sys
-
-config_directory = os.path.dirname(os.path.abspath(__file__))
-sys.path.insert(0, os.path.abspath('.'))
-sys.path.insert(0, os.path.dirname(config_directory))
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom

docs/intro.rst

@@ -164,8 +164,7 @@ for symbols of a model without using labels.
 >>> with model.lock():
 ...     for symbol in model.iter_decisions():
 ...         symbol.set_state(0, [2])
-...     model.objective.state(0) == -4
-True
+...     assert model.objective.state(0) == -4
 
 This process of iterating through a model to select symbols of various types 
 (decision variables, constraints, etc) is helpful when model construction is 
@@ -539,7 +538,7 @@ The two tabs below provide the two formulations.
 	>>> indx = []
 	>>> for i in range(distances.shape()[0]):
 	...     indx.append((itinerary_loc[i,:] * indx_int).sum())
-	>>> model.minimize(add([cost[i]*distances[indx[i], indx[i+1]] for 
+	>>> model.minimize(add(*[cost[i]*distances[indx[i], indx[i+1]] for 
 	...     i in range(distances.shape()[0]-1)]))
 
 	Add explicit one-hot constraints: summing the columns of the 

docs/requirements.txt

@@ -1,2 +1,3 @@
 pydata-sphinx-theme==0.14.3
 sphinx==7.3.7
+sphinx-design==0.5.0

dwave/optimization/model.pyx

@@ -858,7 +858,7 @@ cdef class Model:
             >>> two = model.constant(2)
             >>> i = model.integer()
             >>> model.minimize(two * i - one)
-            >>> G = model.to_networkx()
+            >>> G = model.to_networkx()  # doctest: +SKIP
 
             One advantage of converting to NetworkX is the wide availability
             of drawing tools. See NetworkX's

dwave/optimization/symbols.pyx

@@ -1890,7 +1890,7 @@ cdef class NaryAdd(ArraySymbol):
         >>> i = model.integer((10, 10), lower_bound=-50, upper_bound=50)
         >>> j = model.integer((10, 10), lower_bound=-20, upper_bound=150)
         >>> k = model.integer((10, 10), lower_bound=0, upper_bound=100)
-        >>> l = add([i, j, k])
+        >>> l = add(i, j, k)
         >>> type(l)
         <class 'dwave.optimization.symbols.NaryAdd'>
     """
@@ -1942,7 +1942,7 @@ cdef class NaryMaximum(ArraySymbol):
         >>> i = model.integer((10, 10), lower_bound=-50, upper_bound=50)
         >>> j = model.integer((10, 10), lower_bound=-20, upper_bound=150)
         >>> k = model.integer((10, 10), lower_bound=0, upper_bound=100)
-        >>> l = maximum([i, j, k])
+        >>> l = maximum(i, j, k)
         >>> type(l)
         <class 'dwave.optimization.symbols.NaryMaximum'>
     """
@@ -1994,7 +1994,7 @@ cdef class NaryMinimum(ArraySymbol):
         >>> i = model.integer((10, 10), lower_bound=-50, upper_bound=50)
         >>> j = model.integer((10, 10), lower_bound=-20, upper_bound=150)
         >>> k = model.integer((10, 10), lower_bound=0, upper_bound=100)
-        >>> l = minimum([i, j, k])
+        >>> l = minimum(i, j, k)
         >>> type(l)
         <class 'dwave.optimization.symbols.NaryMinimum'>
     """
@@ -2045,7 +2045,7 @@ cdef class NaryMultiply(ArraySymbol):
         >>> i = model.integer((10, 10), lower_bound=-50, upper_bound=50)
         >>> j = model.integer((10, 10), lower_bound=-20, upper_bound=150)
         >>> k = model.integer((10, 10), lower_bound=0, upper_bound=100)
-        >>> l = multiply([i, j, k])
+        >>> l = multiply(i, j, k)
         >>> type(l)
         <class 'dwave.optimization.symbols.NaryMultiply'>
     """