update API documentation

.github/workflows/docs.yml

@@ -4,7 +4,6 @@ on:
   push:
     branches:    
       - master
-      - develop
 
 jobs:
   build:

README.md

@@ -34,7 +34,7 @@ Flexible discrete optimisation package allowing a quick implementation of your p
 - **Flexibility:** although the algorithms are dependent on each other, it is possible that their internal management is different. This means that the ways in which solutions are evaluated and updated, for example, may be different.
 - **Abstraction:** thanks to the modular separability of the package, it is quickly possible to implement new problems, solutions representation, way to evaluate, update solutions within the package.
 - **Extensible:** the package is open to extension, i.e. it does not partition the user in these developer choices. It can just as well implement continuous optimization problems if needed while making use of the main interaction loop proposed by the package.
-- **Easy Setup:** As a Pure Python package distributed is ``pip`` installable and easy to use.
+- **Easy Setup:** as a pure Python package distributed is ``pip`` installable and easy to use.
 
 
 ## Content

docs/source/api.rst

@@ -1,8 +1,24 @@
 API
 =============
 
-macop
--------------------
+Modules description
+~~~~~~~~~~~~~~~~~~~
+
+**Macop** offers the following main and basic features: 
+
+- **algorithms:** generic and implemented optimisation research algorithms;
+- **callbacks:** callbacks to automatically keep track of the search space advancement;
+- **evaluator:** stores problem instance data and implement a `compute` method in order to evaluate a solution;
+- **operators:** mutators, crossovers update of solution;
+- **policies:** the way you choose the available operators (might be using reinforcement learning);
+- **solutions:** representation of the solution;
+- **validator:** such as constraint programmig, a `validator` is function which is used for validate or not a solution data state.
+
+
+Common and base modules
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The modules presented in this section are common to all types of optimisation problems. The abstract classes proposed here form the basis of the package's structure.
 
 macop.algorithms
 -------------------
@@ -11,6 +27,7 @@ macop.algorithms
    :toctree: macop
    
    macop.algorithms.base
+      
    macop.algorithms.mono
    macop.algorithms.multi
 
@@ -21,6 +38,7 @@ macop.callbacks
    :toctree: macop
    
    macop.callbacks.base
+
    macop.callbacks.classicals
    macop.callbacks.multi
    macop.callbacks.policies
@@ -32,8 +50,6 @@ macop.evaluators
    :toctree: macop
    
    macop.evaluators.base
-   macop.evaluators.discrete.mono
-   macop.evaluators.discrete.multi
 
 macop.operators
 -------------------
@@ -42,12 +58,6 @@ macop.operators
    :toctree: macop
    
    macop.operators.base
-   
-   macop.operators.discrete.mutators
-   macop.operators.discrete.crossovers
-
-   macop.operators.continuous.mutators
-   macop.operators.continuous.crossovers
 
 macop.policies
 -------------------
@@ -56,7 +66,7 @@ macop.policies
    :toctree: macop
    
    macop.policies.base
-   
+      
    macop.policies.classicals
    macop.policies.reinforcement
 
@@ -67,8 +77,6 @@ macop.solutions
    :toctree: macop
 
    macop.solutions.base
-   macop.solutions.discrete
-   macop.solutions.continuous
 
 macop.utils
 -------------------
@@ -77,3 +85,70 @@ macop.utils
    :toctree: macop
 
    macop.utils.progress
+
+
+Discrete Optimisation
+~~~~~~~~~~~~~~~~~~~~~
+
+Some implementations of discrete optimisation problem functionalities are available. They can be used as example implementations or can simply be used by the user.
+
+macop.evaluators
+-------------------
+
+.. autosummary::
+   :toctree: macop
+   
+   macop.evaluators.discrete.mono
+   macop.evaluators.discrete.multi
+
+macop.operators
+-------------------
+
+.. autosummary::
+   :toctree: macop
+   
+   macop.operators.discrete.mutators
+   macop.operators.discrete.crossovers
+
+macop.solutions
+-------------------
+
+.. autosummary::
+   :toctree: macop
+
+   macop.solutions.discrete
+
+
+Continuous Optimisation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Although continuous optimization is not the priority of this package, the idea is to leave the possibility to any user to implement or even propose implementations related to this kind of problem. The modules are here for the moment empty but present to establish the structure relative to these types of implementations.
+
+If a user wishes to propose these developments so that they can be added in a future version of the package, he can refer to the guidelines_ for contributions of the package.
+
+.. _guidelines: https://github.com/prise-3d/macop/blob/master/CONTRIBUTING.md
+
+macop.evaluators
+-------------------
+
+.. autosummary::
+   :toctree: macop
+   
+   macop.evaluators.continuous
+
+macop.operators
+-------------------
+
+.. autosummary::
+   :toctree: macop
+   
+   macop.operators.continuous.mutators
+   macop.operators.continuous.crossovers
+
+macop.solutions
+-------------------
+
+.. autosummary::
+   :toctree: macop
+
+   macop.solutions.continuous

docs/source/conf.py

@@ -73,7 +73,7 @@ html_js_files = [
 # autoapi_dirs = ['../../rawls']
 
 autosummary_generate = True
-autodoc_default_flags = ['members']
+autodoc_default_flags = ['class', 'members', 'inherited-members', 'show-inheritance']
 autodoc_member_order = 'groupwise'
 
 # Add any paths that contain templates here, relative to this directory.

docs/source/description.rst

@@ -27,7 +27,7 @@ Flexible discrete optimisation package allowing a quick implementation of your p
 - **Flexibility:** although the algorithms are dependent on each other, it is possible that their internal management is different. This means that the ways in which solutions are evaluated and updated, for example, may be different.
 - **Abstraction:** thanks to the modular separability of the package, it is quickly possible to implement new problems, solutions representation, way to evaluate, update solutions within the package.
 - **Extensible:** the package is open to extension, i.e. it does not partition the user in these developer choices. It can just as well implement continuous optimization problems if needed while making use of the main interaction loop proposed by the package.
-- **Easy Setup:** As a Pure Python package distributed is ``pip`` installable and easy to use.
+- **Easy Setup:** as a pure Python package distributed is ``pip`` installable and easy to use.
 
 
 

docs/source/index.rst

@@ -38,7 +38,7 @@ Flexible discrete optimisation package allowing a quick implementation of your p
 - **Flexibility:** although the algorithms are dependent on each other, it is possible that their internal management is different. This means that the ways in which solutions are evaluated and updated, for example, may be different.
 - **Abstraction:** thanks to the modular separability of the package, it is quickly possible to implement new problems, solutions representation, way to evaluate, update solutions within the package.
 - **Extensible:** the package is open to extension, i.e. it does not partition the user in these developer choices. It can just as well implement continuous optimization problems if needed while making use of the main interaction loop proposed by the package.
-- **Easy Setup:** As a Pure Python package distributed is `pip` installable and easy to use.
+- **Easy Setup:** as a pure Python package distributed is `pip` installable and easy to use.
 
 
 Indices and tables

docs/source/macop/macop.evaluators.continuous.rst

@@ -0,0 +1,16 @@
+macop.evaluators.continuous
+===========================
+
+.. automodule:: macop.evaluators.continuous
+
+   
+   
+   
+
+   
+   
+   
+
+   
+   
+   

paper.md

@@ -51,7 +51,7 @@ Hence, motivation behind **Macop** is a flexible discrete optimisation package a
 - **Flexibility:** although the algorithms are dependent on each other, it is possible that their internal management is different. This means that the ways in which solutions are evaluated and updated, for example, may be different.
 - **Abstraction:** thanks to the modular separability of the package, it is quickly possible to implement new problems, solutions representation, way to evaluate, update solutions within the package.
 - **Extensible:** the package is open to extension, i.e. it does not partition the user in these developer choices. It can just as well implement continuous optimization problems if needed while making use of the main interaction loop proposed by the package.
-- **Easy Setup:** As a Pure Python package distributed is `pip` installable and easy to use.
+- **Easy Setup:** as a pure Python package distributed is `pip` installable and easy to use.
 
 # Description