diff --git a/.circleci/config.yml b/.circleci/config.yml index 29f022f6..51a4f777 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -146,6 +146,11 @@ jobs: command: | . env/bin/activate make -C docs/ doctest + - run: + name: linkcheck + command: | + . env/bin/activate + make -C docs/ linkcheck || true deploy: docker: diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 4e6e7caf..d7121407 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -26,7 +26,7 @@ the repository owner and they will merge your code in. Follow the commit conventions described here: * https://chris.beams.io/posts/git-commit/ -* http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html +* https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html TL;DR: @@ -122,13 +122,13 @@ Documentation following are exceptions: * For D-Wave extensions of third-party projects, we match the existing convention (e.g. the `D-Wave NetworkX - `_ project follows `NumPy `_ conventions). + `_ project follows `NumPy `_ conventions). * Argument defaults are written "default=x" rather than "default x". * Private functions should include some sort of docstring. * If your module has more than one public unit, it should have a module docstring with a table of contents. * The docstring for the :code:`__init__` method goes on the class. -* All docstrings should be parsable by the `Sphinx `_ documentation generation +* All docstrings should be parsable by the `Sphinx `_ documentation generation tool (i.e. reStructuredText) The sphinx theme should be `readthedocs `_. C++ @@ -153,7 +153,7 @@ Format Versioning Scheme ----------------- -Our code follows `Semantic Versioning `_ conventions: major.minor.patch. +Our code follows `Semantic Versioning `_ conventions: major.minor.patch. A change that breaks backwards compatibility must increment the major version. Anything below version 1.0.0 can break backwards compatibility. diff --git a/docs/conf.py b/docs/conf.py index a30b1c74..d0a53a86 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -98,6 +98,13 @@ # This patterns also effect to html_static_path and html_extra_path exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +linkcheck_ignore=[r'.clang-format', # would need symlink + r'https://cloud.dwavesys.com/leap', # redirects, many checks + r'https://scipy.org', # ignores robots + r'LICENSE', # would need symlink, checked by submodule + r'CONTRIBUTING', # would need symlink, checked by submodule + ] + # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' diff --git a/docs/examples/hybrid1.rst b/docs/examples/hybrid1.rst index 81b85da9..753cd1df 100755 --- a/docs/examples/hybrid1.rst +++ b/docs/examples/hybrid1.rst @@ -59,8 +59,8 @@ Formulate the Problem This example uses a synthetic problem for illustrative purposes: a NetworkX generated graph, -`NetworkX barabasi_albert_graph() `_\ , with random +1 or -1 -couplings assigned to its edges. +`NetworkX barabasi_albert_graph() `_ +, with random +1 or -1 couplings assigned to its edges. .. testcode:: diff --git a/docs/examples/hybrid_solver_service.rst b/docs/examples/hybrid_solver_service.rst index c5d3dc01..12ff5e30 100644 --- a/docs/examples/hybrid_solver_service.rst +++ b/docs/examples/hybrid_solver_service.rst @@ -62,7 +62,7 @@ Formulate the Problem ===================== For a social graph, `G`, this example simply builds a random sparse graph---using the -`NetworkX `_ :func:`~networkx.generators.geometric.random_geometric_graph()` +`NetworkX `_ :func:`~networkx.generators.geometric.random_geometric_graph()` function, which places uniformly at random a specified number of nodes, `problem_node_count`, in a unit cube, joining edges of any two if the distance is below a given radius---and randomly assigns :math:`-1, 1` signs to represent friendly and hostile relationships. diff --git a/docs/examples/inspector_graph_partitioning.rst b/docs/examples/inspector_graph_partitioning.rst index 374b7973..770a3a7a 100644 --- a/docs/examples/inspector_graph_partitioning.rst +++ b/docs/examples/inspector_graph_partitioning.rst @@ -38,7 +38,8 @@ Formulate the Problem This example uses a synthetic problem for illustrative purposes: a NetworkX generated graph, -`NetworkX random_geometric_graph() `_. The problem of interest here, +`NetworkX random_geometric_graph() `_. +The problem of interest here, which is NP-hard, is to try and find the best division of the graph's nodes into two equal sets with a minimum number of edges between the two groups. diff --git a/docs/examples/map_coloring.rst b/docs/examples/map_coloring.rst index b170ef01..dfa190c9 100755 --- a/docs/examples/map_coloring.rst +++ b/docs/examples/map_coloring.rst @@ -37,7 +37,7 @@ To run the code in this example, the following is required. * Ocean tools :doc:`dwavebinarycsp ` and :doc:`dwave-system `. For graphics, - you will also need `NetworkX `_\ . + you will also need `NetworkX `_. .. include:: hybrid_solver_service.rst :start-after: example-requirements-start-marker @@ -119,7 +119,7 @@ The example uses the :doc:`D-Wave binary CSP tool ` to set up constraints and convert the CSP to a binary quadratic model, :doc:`dwave-system ` to set up a D-Wave -system as the :term:`sampler`, and `NetworkX `_ to +system as the :term:`sampler`, and `NetworkX `_ to plot results. >>> import dwavebinarycsp diff --git a/docs/examples/map_dqm.rst b/docs/examples/map_dqm.rst index eb7956b0..e817a956 100755 --- a/docs/examples/map_dqm.rst +++ b/docs/examples/map_dqm.rst @@ -39,7 +39,7 @@ To run the code in this example, the following is required. solutions are those with the lowest values. This is demonstrated in `Leap `_\ 's *Structural Imbalance* demo, introduced in the :ref:`and` example, and comprehensively explained in the - `Problem Solving Handbook `_. + :std:doc:`Problem Solving Handbook `_. Solution Steps ============== @@ -55,7 +55,7 @@ to formulate the problem and submitted to the Formulate the Problem ===================== -This example uses the `NetworkX `_ +This example uses the `NetworkX `_ :func:`~networkx.readwrite.adjlist.read_adjlist` function to read a text file, ``usa.adj``, containing the states of the USA and their adjacencies (states with a shared border) into a graph. The original map information was found on diff --git a/docs/examples/map_kerberos.rst b/docs/examples/map_kerberos.rst index bdf06c23..9ba0ce70 100755 --- a/docs/examples/map_kerberos.rst +++ b/docs/examples/map_kerberos.rst @@ -55,7 +55,7 @@ solve the problem. Formulate the Problem ===================== -This example uses the `NetworkX `_ +This example uses the `NetworkX `_ :func:`~networkx.readwrite.adjlist.read_adjlist` function to read a text file, ``usa.adj``, containing the states of the USA and their adjacencies (states with a shared border) into a graph. The original map information was found on diff --git a/docs/examples/max_cut.rst b/docs/examples/max_cut.rst index 4dea56b4..7147212c 100755 --- a/docs/examples/max_cut.rst +++ b/docs/examples/max_cut.rst @@ -29,11 +29,9 @@ Example Requirements To run the code in this example, the following is required. * The requisite information for problem submission through SAPI, as described in - :ref:`sapi_access`\ , in a configuration file for connection to a D-Wave system, - as described in - `dwave-cloud-client `_\ . -* Installation of Ocean tools `dwave-system `_ and - `dwave_networkx `_\ . + :ref:`sapi_access`. +* Installation of Ocean tools :doc:`dwave-system ` and + :doc:`dwave_networkx `. .. include:: hybrid_solver_service.rst :start-after: example-requirements-start-marker @@ -50,7 +48,7 @@ valid maximum cut. .. note:: As stated in the requirements section above, you should have set up a configuration file for connection to a D-Wave system, as described in - `dwave-cloud-client `_\ . + :doc:`dwave-cloud-client `. The first example code creates a graph that exactly duplicates the structure of a fully working :term:`Chimera` unit cell. It relies on the default embedding of the DWaveSampler to correctly @@ -83,7 +81,7 @@ Optional Example Code .. note:: This example code requires `Matplotlib `_\ . -The Ocean `dwave_networkx `_ +The Ocean :doc:`dwave_networkx ` tool includes some graphic functionality helpful for work on Chimera graphs. The following example code visualizes the graph used in the previous example code. diff --git a/docs/examples/min_vertex.rst b/docs/examples/min_vertex.rst index 82827d09..1779be3e 100755 --- a/docs/examples/min_vertex.rst +++ b/docs/examples/min_vertex.rst @@ -54,7 +54,7 @@ problem of finding such a set is NP hard. A five-node star graph. First, run the code snippet below to create a star graph where node 0 is hub to four other nodes. -The code uses `NetworkX `_\ , which is +The code uses `NetworkX `_\ , which is part of your *dwave_networkx* or *dwave-ocean-sdk* installation. >>> import networkx as nx diff --git a/docs/index.rst b/docs/index.rst index 32a8f1c9..24d3994f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -34,7 +34,6 @@ Packages The Ocean SDK includes the :ref:`dwave_cli` and the following packages: - .. dropdown:: **dimod** --- Quadratic models: BQM, DQM. \ :link-badge:`https://docs.ocean.dwavesys.com/en/stable/docs_dimod/sdk_index.html, "docs", cls=badge-primary fr text-white` \ :link-badge:`https://github.com/dwavesystems/dimod, "code", cls=badge-secondary fr text-white` diff --git a/docs/overview/install.rst b/docs/overview/install.rst index f9409610..4e2b0d3f 100755 --- a/docs/overview/install.rst +++ b/docs/overview/install.rst @@ -18,7 +18,7 @@ versions 3.6 and higher are supported. For information on why many in the Python development community are requiring Python 3, see - `the Python 3 statement `_. + `the Python 3 statement `_. This section explains how to :ref:`install Ocean software`, either the entire suite of tools @@ -50,7 +50,7 @@ depending on your operating system, you may need to first install Python and/or .. attention:: For Windows systems, note that only **64-bit** Python is supported. -#. `Install virtualenv `_ +#. `Install virtualenv `_ describes how to install the `virtualenv` tool for creating isolated Python environments on your local machine for supported operating system. diff --git a/docs/overview/stack.rst b/docs/overview/stack.rst index 83572539..f1e389bf 100755 --- a/docs/overview/stack.rst +++ b/docs/overview/stack.rst @@ -52,7 +52,7 @@ into the following layers of functionality: Tools that help formulate a problem as binary quadratic models; for example :doc:`dwave_networkx ` - (`repo `_\ ) for graph-related problems. + (`repo `_\ ) for graph-related problems. * Application Original problem in its context ("problem space"); for example, circuit fault diagnosis @@ -257,8 +257,8 @@ each stage of the process to a layer of the Ocean stack. Ocean demo applications, which formulate known problems, include: - * `Structural Imbalance `_\ . - * `Circuit-Fault Diagnosis `_\ . + * `Structural Imbalance `_. + * `Circuit-Fault Diagnosis `_. Top-Down Approach