Ref: Rework some of the documentation

docs/source/feature_extractor.rst

@@ -1,7 +1,7 @@
 Feature Extractor
 =================
 
-This package has (Version>=1.1) the ability to use custom feature
+This package has the ability to use custom feature
 extractors for the agent networks. When using a custom feature extractor the
 observations are first fed into the feature extractor and the result is then
 fed into the agent networks. Please see the `stable-baselines3

docs/source/image_based_observations.rst

@@ -1,11 +1,15 @@
 Image based Observations
 ========================
 
+.. Note:: This functionalty has been reworked and the documentation is not up to date. Please check the schema for the renamed/relocated options and functionality.
+
+.. Note:: The solver used in this example is not openly available. The functionality after creating the image should work with any solver.
+
 The framework has now the ability to not only use the spline coordinates as the
 observations but it can also use image based observations. These use flow
-field informations directly from the solver to create a false color image of
+field information directly from the solver to create a false color image of
 the flow field. This means that this feature is currently only available in
-conjuction with the **XNS** solver, from CATS RWTH Aachen. Other solver would
+conjunction with the **XNS** solver, from CATS RWTH Aachen. Other solver would
 need to either do **one** of these options:
 
 #. export the results to the same location and in the same format

docs/source/index.rst

@@ -3,19 +3,42 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to ReLeSO's documentation!
-==================================
 Reinforcement Learning based Shape Optimization (ReLeSO)
 ========================================================
+|Build Status| |Documentation Status|
+|PyPI| |Python| |License|
 
-**ReLeSO** stands for ``Reinforcement Learning based Shape Optimization`` and is a Python framework combining the spline base shape optimization approach with the reinforcement learning.
+.. |Build Status| image:: https://img.shields.io/github/actions/workflow/status/clemens-fricke/releso/pypi_upload
+   :target: https://github.com/clemens-fricke/releso
+   :alt: PyPI - Version
 
-This documentation holds just the usage information and possible configuration parameters of this framework but not the theory behind this approach. Please see the thesis "Python Framework for Reinforcement Learning based Shape Optimization" by Clemens Fricke.  Please contact Clemens Fricke ([email protected]) or Daniel Wolff ([email protected]) to access it.
+.. |Documentation Status| image:: https://readthedocs.org/projects/releso/badge/?version=latest
+    :target: https://releso.readthedocs.io/en/latest/?badge=latest
+    :alt: Documentation Status
 
-This framework is mainly build upon the Python packages ``pydantic`` and ``stable-baselines3``.
+.. .. |codecov| image:: https://codecov.io/gh/clemensfricke/ReLeSO/branch/master/graph/badge.svg
+..     :target: https://codecov.io/gh/clemensfricke/ReLeSO
+..     :alt: Code Coverage
+
+.. |PyPI| image:: https://img.shields.io/pypi/v/releso
+    :target: https://pypi.org/project/releso/
+    :alt: PyPI
+
+.. |Python| image:: https://img.shields.io/pypi/pyversions/releso
+    :target: https://pypi.org/project/releso/
+    :alt: Python
+
+.. |License| image:: https://img.shields.io/pypi/l/releso
+    :target: https://github.com/clemens-fricke/releso/blob/main/LICENSE
+    :alt: PyPI - License
+
+**ReLeSO** stands for ``Reinforcement Learning based Shape Optimization`` and is a Python framework combining the spline base shape optimization approach with reinforcement learning.
+
+This documentation includes the usage information and possible configuration parameters of this framework. Please see the thesis "Python Framework for Reinforcement Learning based Shape Optimization" by Clemens Fricke.  Please contact Clemens Fricke ([email protected]) or Daniel Wolff ([email protected]) to access it.
+We also released two papers with results obtained with this framework, that also go into the theory of the application of Shape Optimization with Reinforcement Learning. The first paper is a short proceedings about the basic concept of concept of ReLeSO for an introductory example to optimzation of extrusion dies [Wolff2023]_ and the second paper is a more detailed paper about the possible optimizations steps towards better learning [Fricke2023]_. In the last paper we compare different agents and the two type RL based Shape Optimization this Framework implements, incremental and direct optimization.
+
+This framework is mainly build upon the Python packages ``pydantic`` and ``stable-baselines3``. Especially the RL agents used are from the ``stable-baselines3`` package. So please refer to the documentation of these packages for further information about the agents and a deeper understanding of RL in general. The documentation given `there <https://stable-baselines3.readthedocs.io/en/master/>`_ is very good and easy to understand.
 
-.. note::
-   This project is still under development.
 
 For guidance on the installation process see :doc:`installation`.
 
@@ -37,3 +60,8 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
+
+
+.. [Wolff2023] Wolff, D., Fricke, C., Kemmerling, M., & Elgeti, S. (2023). `Towards shape optimization of flow channels in profile extrusion dies using reinforcement learning <https://onlinelibrary.wiley.com/doi/abs/10.1002/pamm.202200009>`_. PAMM, 22(1), e202200009
+
+.. [Fricke2023] Fricke, C., Wolff, D., Kemmerling, M., & Elgeti, S. (2023). `Investigation of reinforcement learning for shape optimization of 2D profile extrusion die geometries <https://www.aimsciences.org/article/doi/10.3934/acse.2023001>`_. Advances in Computational Science and Engineering, 1(1), 1-35.

docs/source/installation.rst

@@ -1,62 +1,54 @@
 Installation
 ============
 
-This page covers the installation process of the framework and its prerequisites.
-
-Prerequisites
--------------
-To use ReLeSO the following packages have to be installed:
- - pydantic<2.0
- - stable-baselines3
- - tensorboard
- - torchvision
- - hjson
- - gustaf
-
-The first two/three packages can be installed via pip and/or conda with the following command:
-
-**pip** (activation of the venv should be done beforehand)
+The package is available via PyPI and can be installed via pip:
 
 .. code-block:: console
 
-   (.venv) $ pip install "pydantic<2.0" stable-baselines3 tensorboard hjson
+   (env) $ pip install releso
 
-**conda**
-
-.. code-block:: console
+This command will install the package with the minimal dependencies.
 
-   (base) $ conda create -n releso python=3.9 pydantic<2.0 tensorboard
-   (base) $ conda activate releso
-   (releso) $ conda install -c pytorch torchvision
-   (releso) $ pip install stable-baselines3 hjson
+The following packages are optional and bring further capabilities to the framework:
+ - splinepy -> Spline based geometries
+ - gustaf -> If Free Form Deformations is used
+ - torchvision -> If Image based observations are used
 
-The next step is to install the ``gustaf`` package which is a python interface for the c++ library SplineLib.
-To install ``gustaf`` the following repository must be downloaded into an external folder and installed into the venv or conda environment as before. The installation process for the gustaf package is documented in the README file of the repository.
+These can be automatically install via the following command:
 
+.. code-block:: console
 
-**Development**
+   (env) $ pip install "releso[all]"
 
-To develop the framework further the sphinx package should also be installed with the currently used sphinx html theme ``sphinx_rtd_theme``.
-The this can be done via:
 
-.. code-block:: console
+.. note::
+    It is recommended to use a environment manager like conda to install the packages into an environment.
 
-   (releso) $ pip install sphinx sphinx_rtd_theme
+Installation from source
+------------------------
 
-Framework
----------
+Clone the `repository <https://github.com/clemens-fricke/releso>`_ from github.
 
-After installing all prerequisites the framework itself can be installed by running the command below in the main repository folder
+There are two modes that a package can be installed from source.
 
 **Non-development**
 
+The package is basically installed like it would from PyPI. This can be done via:
+
 .. code-block:: console
 
    (releso) $ pip install .
 
 
 **Development**
+The development mode of *pip install* allows to change the source code and have the changed
+directly reflected in the installed package. Meaning no recompliation before starting the
+next script call is necessary (If you use an IPython kernel you will have to restart the kernel
+to see the changes). This is done by adding the ``-e`` flag to the pip install command.
+The development mode can be installed via:
 
 .. code-block:: console
 
-   (releso) $ pip install -e .
+   (releso) $ pip install -e ".[dev]"
+
+The def extension will install all optional dependencies as well as the development dependencies.

docs/source/json_schema.rst

@@ -2,5 +2,7 @@ JSON SCHEMA ReLeSO
 ===================
 The input file must be written to comply to the following json-schema.
 
-.. literalinclude:: ../../schema.json
-    :language: json
+.. jsonschema:: ../../schema.json
+    :lift_definitions:
+    :auto_reference:
+    :auto_target: