Merge branch 'topics/doc'

README.rst

@@ -1,13 +1,18 @@
 .. Copyright 2023 Vincent Jacques
 
-.. WARNING, this README is rendered to HTML in several places
+.. This README is rendered to HTML in several places
     - on GitHub (https://github.com/mics-lab/lincs/)
     - on PyPI after publication of the package (https://pypi.org/project/lincs/)
     - on GitHub Pages (https://mics-lab.github.io/lincs/)
     So when you change it, take care to check all those places.
 
-*lincs* (Learn and Infer Non Compensatory Sortings) is a collection of MCDA algorithms, usable as a command-line utility.
-We plan to make it usable as a C++ library and a Python (3.7+) package as well. (@todo(Feature, later))
+*lincs* (Learn and Infer Non Compensatory Sortings) is a collection of `MCDA <https://en.wikipedia.org/wiki/Multiple-criteria_decision_analysis>`_ algorithms, usable as a command-line utility.
+
+@todo(Feature, later) Make it usable as a Python package.
+
+@todo(Feature, later) Make it usable as a C++ library.
+
+*lincs* supports Linux, macOS and Windows, with the exception that GPU-based algorithms are not available on macOS, because CUDA itself is not available there.
 
 *lincs* is licensed under the GNU Lesser General Public License v3.0 as indicated by the two files `COPYING <COPYING>`_ and `COPYING.LESSER <COPYING.LESSER>`_.
 
@@ -20,10 +25,8 @@ and its `source code <https://github.com/mics-lab/lincs/>`_ are on GitHub.
 Questions? Remarks? Bugs? Want to contribute? Open `an issue <https://github.com/MICS-Lab/lincs/issues>`_ or `a discussion <https://github.com/MICS-Lab/lincs/discussions>`_!
 
 
-@todo(Documentation, soon) Add array summerizing the support of each OS
-
-Contributors and previous work
-==============================
+Contributors
+============
 
 *lincs* is developed by the `MICS <https://mics.centralesupelec.fr/>`_ research team at `CentraleSupélec <https://www.centralesupelec.fr/>`_.
 
@@ -34,57 +37,6 @@ Its main authors are (alphabetical order):
 - `Vincent Mousseau <https://www.centralesupelec.fr/fr/2EBDCB86-64A4-4747-96E8-C3066CB61F3D>`_ (domain expertise)
 - `Wassila Ouerdane <https://wassilaouerdane.github.io/>`_ (domain expertise)
 
-Fondamental concepts
---------------------
-
-*lincs* is based on the following concepts.
-Note that we describe them in our `conceptual overview documentation <https://mics-lab.github.io/lincs/conceptual-overview.html>`_.
-This section is here to give credit to their authors.
-
-The Non-Compensatory Sorting (NCS) model
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The concept of the NCS model was first introduced by Denis Bouyssou and Thierry Marchant in their articles `An axiomatic approach to noncompensatory sorting methods in MCDM I: The case of two categories <https://hal.science/hal-00958022>`_ and `... II: More than two categories <https://hal.science/hal-00013762v1>`_.
-
-Particular cases of the NCS model
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The Uc-NCS model is a particular case of the NCS model.
-
-The MR-Sort model is a particular case of the Uc-NCS model introduced by Agnès Leroy *et al.* in `Learning the Parameters of a Multiple Criteria Sorting Method <https://link.springer.com/chapter/10.1007/978-3-642-24873-3_17>`_.
-
-Although *lincs* can sort alternatives according to general NCS models (without veto), it only implements learning Uc-NCS and MR-Sort models.
-
-Learning algorithms
--------------------
-
-*lincs* provides new implementations of the following algorithms:
-
-@todo(Documentation, soon) Change this section into an array with each alogorithm's caracteristics
-
-Learning Uc-NCS models with a SAT-based approaches
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The following learning algorithms were implemented using their description by Ali Tlili, Khaled Belahcène *et al.* in `Learning non-compensatory sorting models using efficient SAT/MaxSAT formulations <https://www.sciencedirect.com/science/article/abs/pii/S0377221721006858>`_:
-
-- learning exact Uc-NCS models with a "SAT by coalitions" approach
-- learning approximate Uc-NCS models with a "max-SAT by coalitions" approach
-- learning exact Uc-NCS models with a "SAT by separation" approach
-- learning approximate Uc-NCS models with a "max-SAT by separation" approach
-
-Note that they were introduced in previous articles, and that this article conveniently gathers them in a single place.
-
-Learning approximate MR-Sort with a heuristic approach
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This approach, described by `Olivier Sobrie <http://olivier.sobrie.be/>`_ in his `Ph.D thesis <http://olivier.sobrie.be/papers/phd_2016_sobrie.pdf>`_,
-is based on splitting the learning into three phases: optimize the weights (linear programming), improve the profiles (heuristic) and breed the population of intermediate models.
-We call it the "weights, profiles, breed" learning strategy in *lincs*.
-
-It was originaly `implemented in Python <https://github.com/oso/pymcda>`_ by Olivier Sobrie.
-Emma Dixneuf, Thibault Monsel and Thomas Vindard then provided a sequential `C++ implementation of Sobrie's heuristic <https://github.com/Mostah/fastPL/>`_.
-*lincs* provides two parallel implementations of this approach (using OpenMP and CUDA).
-
 
 Project goals
 =============
@@ -93,7 +45,7 @@ Provide MCDA tools usable out of the box
 ----------------------------------------
 
 You should be able to use *lincs* without being a specialist of MCDA and/or NCS models.
-Just follow the `Get started <#get-started>`_ section below.
+Just follow the "Get started" section below.
 
 Provide a base for developing new MCDA algorithms
 -------------------------------------------------
@@ -118,10 +70,17 @@ and `reference documentation <https://mics-lab.github.io/lincs/reference.html>`_
 Versioning
 ==========
 
-Starting with version 1.0.0, *lincs* tries to apply `semantic versioning <https://semver.org/>`_ at a *code* level:
-upgrading patch and minor releases should not require changes in client code but may require you to recompile and link it.
+Starting with version 1.0.0, *lincs* uses `semantic versioning <https://semver.org/>`_.
+
+*lincs*' public API (that "must be declared" according to SemVer) is constituted exclusively by its `reference documentation <https://mics-lab.github.io/lincs/reference.html>`_,
+**at a code level**: we consider a change as backward compatible if the client code doesn't need to be modified to keep working,
+even if that change requires recompiling the client code in some cases.
+
+A backward compatible change might change *lincs*' behavior, especially with regards to pseudo-random behavior.
 
-@todo(Documentation, v1) Be explicit about the semver contract
+Note that we plan to make *lincs* usable as Python and C++ libraries.
+When we do that, we'll add these interfaces to the public API.
+In the mean time, if you chose to use *lincs* that way, you must expect unanticipated changes to these interfaces.
 
 
 Develop *lincs* itself

development/cycle.py

@@ -244,33 +244,37 @@ def build_sphinx_documentation():
     with open("README.rst") as f:
         original_content = f.read()
 
-    content = original_content
-    content = re.sub(r"`(.*) <https://mics-lab.github.io/lincs/(.*)\.html>`_", r":doc:`\1 <\2>`", content)
+    try:
+        content = re.sub(r"`(.*) <https://mics-lab.github.io/lincs/(.*)\.html>`_", r":doc:`\1 <\2>`", original_content)
 
-    with open("README.rst", "w") as f:
-        f.write(content)
+        with open("README.rst", "w") as f:
+            f.write(content)
 
-    with open("doc-sources/problem-schema.yml", "w") as f:
-        subprocess.run(["python3", "-c", "import lincs; print(lincs.Problem.JSON_SCHEMA, end='')"], check=True, stdout=f)
+        with open("doc-sources/problem-schema.yml", "w") as f:
+            subprocess.run(["python3", "-c", "import lincs; print(lincs.Problem.JSON_SCHEMA, end='')"], check=True, stdout=f)
 
-    with open("doc-sources/model-schema.yml", "w") as f:
-        subprocess.run(["python3", "-c", "import lincs; print(lincs.Model.JSON_SCHEMA, end='')"], check=True, stdout=f)
+        with open("doc-sources/model-schema.yml", "w") as f:
+            subprocess.run(["python3", "-c", "import lincs; print(lincs.Model.JSON_SCHEMA, end='')"], check=True, stdout=f)
 
-    shutil.rmtree("docs", ignore_errors=True)
-    subprocess.run(
-        [
-            "sphinx-build",
-            "-b", "html",
-            "--jobs", str(multiprocessing.cpu_count() - 1),
-            "doc-sources", "docs",
-        ],
-        check=True,
-    )
+        shutil.rmtree("docs", ignore_errors=True)
+        subprocess.run(
+            [
+                "sphinx-build",
+                "-b", "html",
+                "--jobs", str(multiprocessing.cpu_count() - 1),
+                "doc-sources", "docs",
+            ],
+            check=True,
+        )
+
+        os.unlink("doc-sources/problem-schema.yml")
+        os.unlink("doc-sources/model-schema.yml")
 
-    os.unlink("doc-sources/problem-schema.yml")
-    os.unlink("doc-sources/model-schema.yml")
-    with open("README.rst", "w") as f:
-        f.write(original_content)
+        shutil.copy("COPYING", "docs/")
+        shutil.copy("COPYING.LESSER", "docs/")
+    finally:
+        with open("README.rst", "w") as f:
+            f.write(original_content)
 
 
 def run_integration_tests(*, skip_long, forbid_gpu):