From 5c2172a7aa99bfab0f19b9eba57900958e0d9641 Mon Sep 17 00:00:00 2001 From: Alexander Condello Date: Fri, 12 Jul 2024 08:41:33 -0700 Subject: [PATCH 1/4] Build locally with the same sphinx theme as the sdk --- docs/conf.py | 28 ++++++---------------------- docs/requirements.txt | 5 ++--- 2 files changed, 8 insertions(+), 25 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index f58415df..b71f9b87 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -85,31 +85,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, diff --git a/docs/requirements.txt b/docs/requirements.txt index aab40801..d094c0c2 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,2 @@ -sphinx -sphinx_rtd_theme -sphinx-design==0.5.0 +pydata-sphinx-theme==0.14.3 +sphinx==7.3.7 From 2f50dacd338475215b3ed34d075fbdc301e1c9bb Mon Sep 17 00:00:00 2001 From: Alexander Condello Date: Fri, 12 Jul 2024 08:48:06 -0700 Subject: [PATCH 2/4] Remove |version| from the docs See https://github.com/dwavesystems/dwave-optimization/issues/54 --- docs/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index e808f783..3bca228e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,7 +14,6 @@ Documentation .. only:: html - :Release: |version| :Date: |today| .. sdk-start-marker From 65a6287c32d0da5fcbb2f4b6e3ba46c805731b10 Mon Sep 17 00:00:00 2001 From: Alexander Condello Date: Fri, 12 Jul 2024 08:56:42 -0700 Subject: [PATCH 3/4] Add doctests in CI --- .circleci/config.yml | 33 +++++++++++++++++++++++++++++++++ docs/conf.py | 8 -------- docs/intro.rst | 5 ++--- docs/requirements.txt | 1 + dwave/optimization/model.pyx | 2 +- dwave/optimization/symbols.pyx | 8 ++++---- 6 files changed, 41 insertions(+), 16 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 7dd71133..3f69223d 100644 --- a/.circleci/config.yml +++ b/.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: diff --git a/docs/conf.py b/docs/conf.py index b71f9b87..615e15f3 100644 --- a/docs/conf.py +++ b/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 diff --git a/docs/intro.rst b/docs/intro.rst index 46912f91..80bddd80 100644 --- a/docs/intro.rst +++ b/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 diff --git a/docs/requirements.txt b/docs/requirements.txt index d094c0c2..90727eda 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,2 +1,3 @@ pydata-sphinx-theme==0.14.3 sphinx==7.3.7 +sphinx-design==0.5.0 diff --git a/dwave/optimization/model.pyx b/dwave/optimization/model.pyx index 2a421166..6e278a78 100644 --- a/dwave/optimization/model.pyx +++ b/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 diff --git a/dwave/optimization/symbols.pyx b/dwave/optimization/symbols.pyx index 6e58371c..ed903504 100644 --- a/dwave/optimization/symbols.pyx +++ b/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) """ @@ -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) """ @@ -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) """ @@ -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) """ From 278c7ce402470b51742cbb71425726f4e666c8f0 Mon Sep 17 00:00:00 2001 From: Alexander Condello Date: Fri, 12 Jul 2024 11:00:31 -0700 Subject: [PATCH 4/4] Specify language in sphinx's conf.py --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 615e15f3..4c98d826 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -48,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