fix reference documentation

ROADMAP.md

@@ -23,5 +23,6 @@
 - test vectorize
 
 # Docs
-- document examples: in installation chapter (with CLI) and also in reference (with code?)
+- installation : put links to examples (and not CSPLIB)
+- examples : link to github
 - improve usage of rst

docs/source/conf.py

@@ -11,6 +11,8 @@
 
 # -- General configuration
 
+tls_verify = False
+
 extensions = [
     'sphinx.ext.duration',
     'sphinx.ext.doctest',
@@ -40,4 +42,5 @@
 }
 
 # -- Options for EPUB output
-epub_show_urls = 'footnote'
+epub_show_urls = 'footnote'
+

docs/source/propagators.rst → docs/source/consistency_propagators.rst

@@ -2,8 +2,6 @@
 Consistency and propagators
 ###########################
 
-
-
 ***********
 Consistency
 ***********
@@ -15,6 +13,8 @@ NUCS implements bound consistency out-of-the box and supports custom consistency
 *****************************
 Propagators (aka constraints)
 *****************************
+
+NUCS comes with some highly-optimized :ref:`propagators <propagators>`.
 Each propagator :code:`XXX` defines three functions:
 
 - :code:`compute_domains_XXX(domains: NDArray, data: NDArray) -> int`

docs/source/index.rst

@@ -25,6 +25,6 @@ Contents
 .. toctree::
 
    installation
-   domains
-   propagators
+   variables_domains
+   consistency_propagators
    reference

docs/source/installation.rst

@@ -2,8 +2,6 @@
 Installation
 ############
 
-.. _installation:
-
 ************************
 Install the NUCS package
 ************************
@@ -12,13 +10,13 @@ Let's install the NUCS package with pip:
 
 .. code-block:: bash
 
-   $ pip install nucs
+   pip install nucs
 
 *****************
 Run some examples
 *****************
 
-NUCS comes with some models and heuristics for some well-known problems.
+NUCS comes with some models and :ref:`heuristics <heuristics>` for some well-known :ref:`examples <examples>`.
 Some of these examples have a command line interface and can be run directly.
 
 Solve the 12-queens problem
@@ -66,7 +64,6 @@ Let's find the optimal solution to the `Golomb ruler problem <https://www.csplib
    }
    [1, 6, 10, 23, 26, 34, 41, 53, 55]
 
-
 **********************
 Write your first model
 **********************

docs/source/reference.rst

@@ -2,46 +2,96 @@
 Reference documentation
 #######################
 
+
+.. _propagators:
+
 ***********
 Propagators
 ***********
 
-NUCS currently provides the following propagators:
-
-- :code:`affine_eq_propagator`
-- :code:`affine_geq_propagator`
-- :code:`affine_leq_propagator`
-- :code:`alldifferent_propagator`
-- :code:`count_eq_propagator`
-- :code:`element_lic_propagator`
-- :code:`element_liv_propagator`
-- :code:`exactly_eq_propagator`
-- :code:`lexicographic_leq_propagator`
-- :code:`max_eq_propagator`
-- :code:`max_leq_propagator`
-- :code:`min_eq_propagator`
-- :code:`min_geq_propagator`
-- :code:`relation_propagator`
+NUCS currently provides the following highly-optimized propagators.
+
+==================================== ============================================== ========================
+Name                                 Definition                                     Complexity
+==================================== ============================================== ========================
+:code:`affine_eq_propagator`         :math:`\Sigma_i a_i \times x_i = a_{n-1}`      :math:`n`
+:code:`affine_geq_propagator`        :math:`\Sigma_i a_i \times x_i \geq a_{n-1}`   :math:`n`
+:code:`affine_leq_propagator`        :math:`\Sigma_i a_i \times x_i \leq a_{n-1}`   :math:`n`
+:code:`alldifferent_propagator`      :math:`\forall i, j, x_i \neq x_j`             :math:`n \times log(n)`
+:code:`count_eq_propagator`          :math:`\Sigma_i (x_i = a) = x_{n-1}`           :math:`n`
+:code:`element_lic_propagator`       :math:`l_i = c`                                :math:`n`
+:code:`element_liv_propagator`       :math:`l_i = x`                                :math:`n`
+:code:`exactly_eq_propagator`        :math:`\Sigma_i (x_i = a_0) = a_1`             :math:`n`
+:code:`lexicographic_leq_propagator` :math:`x \leq_{lex} y`                         :math:`n`
+:code:`max_eq_propagator`            :math:`\max_i x_i = x_{n-1}`                   :math:`n`
+:code:`max_leq_propagator`           :math:`\max_i x_i \leq x_{n-1}`                :math:`n`
+:code:`min_eq_propagator`            :math:`\min_i x_i = x_{n-1}`                   :math:`n`
+:code:`min_geq_propagator`           :math:`\min_i x_i \geq x_{n-1}`                :math:`n`
+:code:`relation_propagator`          Relation defined in extension                  :math:`n`
+==================================== ============================================== ========================
+
+.. _heuristics:
 
 **********
 Heuristics
 **********
 
-Functions for selecting a shared domain
-#######################################
+NUCS provides heuristics for selecting a variable (precisely selecting a shared domain)
+and for selecting a value (more generally, reducing the shared domain):
+
+Heuristics for selecting a shared domain
+########################################
+
+NUCS provides the following functions for selecting a shared domain.
+
+============================================ ============================================================
+Function                                     Description
+============================================ ============================================================
+:code:`first_not_instantiated_var_heuristic` selects the first non-instantiated shared domain
+:code:`last_not_instantiated_var_heuristic`  selects the last non-instantiated shared domain
+:code:`smallest_domain_var_heuristic`        selects the smallest shared domain which is not instantiated
+:code:`greatest_domain_var_heuristic`        selects the greatest shared domain which is not instantiated
+============================================ ============================================================
+
+Heuristics for reducing the chosen shared domain
+################################################
+
+NUCS provides the following functions for reducing a shared domain.
+
+============================================ ============================================================
+Function                                     Description
+============================================ ============================================================
+:code:`min_value_dom_heuristic`              selects the minimal value of the domain
+:code:`max_value_dom_heuristic`              selects the maximal value of the domain
+:code:`split_low_dom_heuristic`              selects the first half of the domain
+============================================ ============================================================
 
-- :code:`first_not_instantiated_var_heuristic`: selects the first non-instantiated shared domain
-- :code:`last_not_instantiated_var_heuristic`: selects the last non-instantiated shared domain
-- :code:`smallest_domain_var_heuristic`: selects the smallest shared domain which is not instantiated
-- :code:`greatest_domain_var_heuristic`: selects the greatest shared domain which is not instantiated
+.. _examples:
 
-Functions for reducing the chosen shared domain
-###############################################
-- :code:`min_value_dom_heuristic`: selects the minimal value of the domain
-- :code:`max_value_dom_heuristic`: selects the maximal value of the domain
-- :code:`split_low_dom_heuristic`: selects the first half of the domain
+********
+Examples
+********
 
+NUCS comes with the following examples.
+Some of these examples have a command line interface and can be run directly:
 
+.. code-block:: bash
 
+   NUMBA_CACHE_DIR=.numba/cache PYTHON_PATH=. python -m nucs.examples.<problem> <options>
 
+================================ ======== ======================== =====================================================
+Problem                          CSPLib # CLI                      Options
+================================ ======== ======================== =====================================================
+:code:`alpha`                             Yes
+:code:`bibd`                     028      Yes (for one instance)
+:code:`donald`                            Yes
+:code:`golomb`                   006      Yes                      :code:`-n` size
+:code:`knapsack`                 133      Yes (for one instance)
+:code:`magic_sequence`           019
+:code:`magic_square`             019
+:code:`quasigroup`               003      Yes (for one subproblem) :code:`-n` size
+:code:`queens`                   054      Yes                      :code:`-n` size
+:code:`schur_lemma`              015
+:code:`sudoku`
+================================ ======== ======================== =====================================================