Merge pull request #55 from arcondello/docs/flat-symbols

Improve doc testing

.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
@@ -56,7 +48,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 add_module_names = False
 # List of patterns, relative to source directory, that match files and
@@ -85,31 +77,15 @@
 
 """
 
-# -- Breath ---------------------------------------------------------------
-
-# breathe_default_project = "dwave.optimization"
-# breathe_projects = dict(
-#   optimization=os.path.join(config_directory, 'build-cpp', 'xml'),
-#   )
-
-# see https://breathe.readthedocs.io/en/latest/readthedocs.html
-# if os.environ.get('READTHEDOCS', False):
-#     subprocess.call('make cpp', shell=True, cwd=config_directory)
-
 # -- Options for HTML output ----------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
-import sphinx_rtd_theme
-html_theme = 'sphinx_rtd_theme'
-html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+html_theme = "pydata_sphinx_theme"
 
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#
-# html_theme_options = {}
+html_theme_options = {
+    "collapse_navigation": True,
+    "show_prev_next": False,
+}
+html_sidebars = {"**": ["search-field", "sidebar-nav-bs"]}  # remove ads
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

docs/index.rst

@@ -14,7 +14,6 @@ Documentation
 
 .. only:: html
 
-  :Release: |version|
   :Date: |today|
 
 .. sdk-start-marker

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,3 +1,3 @@
-sphinx
-sphinx_rtd_theme
+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'>
     """