merge documentation changes into release for v0.1.5

nicolaipalm · Jul 4, 2023 · aa68c31 · aa68c31
2 parents 0649103 + 90f04e2
commit aa68c31
Show file tree

Hide file tree

Showing 30 changed files with 350 additions and 547 deletions.
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 [![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg?style=plastic)](https://www.python.org/downloads/)
 
 
-[documentation]()//[notebooks]()
+[documentation](https://paref.readthedocs.io/en/latest/)//[notebooks](https://github.com/nicolaipalm/paref/tree/main/docs/notebooks)
 
 # Paref - using and building problem tailored MOO
 
@@ -11,14 +11,13 @@ properties](#what-are-properties-of-pareto-points)** identified (Pareto) points
 The fact that these characteristics are fulfilled is what makes a MOO successful in the first place.
 Why not construct a MOO algorithm which searches exactly for those properties?
 With the language of PAreto REFlections this is now possible.
-This package contains
+This package contains...
 
-- a series of ready-to-use [MOO algorithms](table below) corresponding to frequently targeted properties
-- a framework for you to implement your problem specific MOO algorithm
-- generic and intuitive [interfaces]() for MOO algorithms, blackbox functions and more such that solving an MOO problem with Paref requires minimal effort
-- documentation including [how-to guides](), [examples](), [check sheets]() and Parefs' [architecture]() so that getting started with and using Paref becomes easy
+- a series of ready-to-use [MOO algorithms](https://github.com/nicolaipalm/paref/tree/main/paref/moo_algorithms) corresponding to frequently targeted properties
+- a framework for you to implement your problem tailored MOO algorithm
+- generic and intuitive [interfaces](https://github.com/nicolaipalm/paref/tree/main/paref/interfaces) for MOO algorithms, black-box functions and more, so solving a MOO problem with user-defined properties with Paref requires only minimal effort
 
-See the official [documentation](https://github.com/) for more information.
+See the official [documentation](https://paref.readthedocs.io/en/latest/) for more information.
 
 ## Content
 
@@ -34,45 +33,29 @@ The official release is available at PyPi:
 pip install paref
 ```
 
-You can clone this repository by running the following command:
-
-```
-git clone https://github.com/nicolaipalm/paref
-cd paref
-pip install
-```
-
-In your python terminal run (hello world where left side of w is pareto front)
-
-```python
-from paref.
-```
-
 ## Usage
 
-> 💡 See the [how-to guides]() for a more detailled description.
-
 Solving an MOO problem with Paref consists of the following steps
 
-0. [Define design and target space]()
-1. Define desired [properties](#what-are-properties-of-pareto-points) of Pareto points
-2. Initialize corresponding [MOO algorithm](link moo algos)
-3. [Implement and initialize bbf](link how to implement bbf)
-4. [Apply problem tailored MOO algorithm to blackbox function](link how to apply moo)
+0. Define design and target space
+1. Define desired properties of Pareto points
+2. Initialize corresponding MOO algorithm
+3. Implement and initialize bbf
+4. Apply problem tailored MOO algorithm to blackbox function
 
 This may look as follows:
 
 0. We use a mathematical test function with three input dimensions all between zero and one (i.e. design space is given by three-dimensional unit cube) and with two output dimensions (i.e. target space is the real plane)
 1. We want to have an idea of the "dimension" of the Pareto front (i.e. the Pareto points representing the minima in
    components) with minimum number of evaluations
-2. Accordingly, we choose the [FindEdgePoints]() algorithm:
+2. Accordingly, we choose the ``FindEdgePoints`` algorithm:
 
 ```python
 from paref.moo_algorithms.multi_dimensional.find_edge_points import FindEdgePoints
 moo = FindEdgePoints()
 ```
 
-3. We [implement](how-to-implement) and initialize the blackbox function in the Paref blackbox function interface
+3. We implement and initialize the blackbox function in the Paref blackbox function interface
 
 ```python
 import numpy as np
@@ -118,9 +101,9 @@ In mathematical terms, we understand properties of Pareto points as being elemen
 
 They include but are certainly not limited to the following:
 
-|              Property               |                                       Graphic                                        | Example | Algorithm(s) |Sequence|Pareto reflection|
-|:-----------------------------------:|:------------------------------------------------------------------------------------:|:------------:|:------------:|:-----:|:-----:|
-|         Being an edge point         |     ![Edge point](./docs/graphics/plots/reflections/FindEdgePointsSequence.svg)      |||||
-|            Filling a gap            |             ![Fill gap](./docs/graphics/plots/reflections/FillGap2D.svg)             |||||
-|      Being evenly distributed       | ![Edge point](./docs/graphics/plots/reflections/FillGapsOfParetoFrontSequence2D.svg) |||||
-| Being constrained to a defined area |        ![Fill gap](./docs/graphics/plots/reflections/RestrictByPoint.svg)         |||||
+|              Property               |                                       Graphic                                        | Example |                        Algorithm(s)                         |          Sequence           |  Pareto reflection   |
+|:-----------------------------------:|:------------------------------------------------------------------------------------:|:-------:|:-----------------------------------------------------------:|:---------------------------:|:--------------------:|
+|         Being an edge point         |     ![Edge point](./docs/graphics/plots/reflections/FindEdgePointsSequence.svg)      |         |                     ``FindEdgePoints``                      | ``FindEdgePointsSequence``  |                      |
+|            Filling a gap            |             ![Fill gap](./docs/graphics/plots/reflections/FillGap2D.svg)             |         |                                                             |                             |    ``FillGap2D``     |
+|      Being evenly distributed       | ![Edge point](./docs/graphics/plots/reflections/FillGapsOfParetoFrontSequence2D.svg) |         | ``FindEdgePoints`` followed by ``FillGapsOfParetoFront2D``  |                             |                      |
+| Being constrained to a defined area |          ![Fill gap](./docs/graphics/plots/reflections/RestrictByPoint.svg)          |         |                                                             |                             | ``RestrictByPoint``  |
diff --git a/docs/.readthedocs.yaml b/docs/.readthedocs.yaml
@@ -0,0 +1,22 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.9"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Optionally declare the Python requirements required to build your docs
+python:
+   install:
+   - requirements: docs/requirements.txt
+   - requirements: requirements.txt
diff --git a/docs/api.rst b/docs/api.rst
@@ -0,0 +1,56 @@
+API Reference
+=============
+This page contains the API reference for public objects and functions in ``paref``.
+
+
+.. autosummary::
+    :toctree: api
+    :recursive:
+
+    paref.moo_algorithms
+    paref.pareto_reflection_sequences
+    paref.pareto_reflections
+    paref.black_box_functions
+    paref.interfaces
+
+
+
+MOO algorithms
+--------------
+.. autosummary::
+    :nosignatures:
+
+    paref.interfaces.moo_algorithms
+    paref.moo_algorithms.minimizer
+    paref.moo_algorithms.two_dimensional
+    paref.moo_algorithms.multi_dimensional
+
+
+
+
+Stopping criteria
+-----------------
+.. autosummary::
+    :nosignatures:
+
+    paref.interfaces.moo_algorithms
+    paref.moo_algorithms.stopping_criteria
+
+
+Sequences of Pareto reflections
+-------------------------------
+.. autosummary::
+    :nosignatures:
+
+    paref.interfaces.sequences_pareto_reflections
+    paref.pareto_reflection_sequences.two_dimensional
+    paref.pareto_reflection_sequences.multi_dimensional
+    paref.pareto_reflection_sequences.generic
+
+Pareto reflections
+------------------
+.. autosummary::
+    :nosignatures:
+
+    paref.interfaces.pareto_reflections
+    paref.pareto_reflections
diff --git a/docs/conf.py b/docs/conf.py
@@ -12,16 +12,15 @@
 #
 import os
 import sys
-sys.path.insert(0, os.path.abspath('../'))
 
+sys.path.insert(0, os.path.abspath('../'))
 
 # -- Project information -----------------------------------------------------
 
 project = 'paref'
 copyright = '2023, Nicolai Palm'
 author = 'Nicolai Palm'
 
-
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
@@ -35,28 +34,29 @@
     'myst_parser',
     'nbsphinx',
     'sphinx_copybutton',
-    'sphinx_gallery.load_style',
+    'sphinx_design',
+    'IPython.sphinxext.ipython_console_highlighting',
+    'sphinx.ext.autosectionlabel',
 ]
 
 nbsphinx_execute = 'never'
 
-autoclass_content = 'both'
+myst_enable_extensions = ['colon_fence']
 
 # Add any paths that contain templates here, relative to this directory.
 # templates_path = ['_templates']
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', '**.ipynb_checkpoints']
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
 html_theme = 'pydata_sphinx_theme'
-# html_theme = "sphinxawesome_theme"
 html_theme_path = ['_themes', ]
 
 html_theme_options = {
@@ -70,3 +70,19 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 # html_static_path = ['_static']
+
+
+# -- Autodoc ---------------------------------------------------------------------------------------
+autosummary_generate = True
+autodoc_default_options = {
+    'show-inheritance': True,
+    'members': True,
+    'member-order': 'groupwise',
+    'special-members': '__call__',
+    'undoc-members': True,
+}
+autoclass_content = 'both'
+autodoc_inherit_docstrings = False
+
+# -- Read the Docs ---------------------------------------------------------------------------------
+master_doc = 'index'
diff --git a/docs/description/architecture.md b/docs/description/architecture.md
diff --git a/docs/description/check-sheet.md b/docs/description/check-sheet.md