Fix the docs build on read the docs (#17)

.github/workflows/build_and_upload_wheels.yml

@@ -1,4 +1,4 @@
-name: pypi upload
+name: pypi_upload
 
 on:
   push:

.readthedocs.yml

@@ -10,6 +10,9 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.12"
+  jobs:
+    pre_build:
+      - python3 schema.py
     # You can also specify other tool versions:
     # nodejs: "19"
     # rust: "1.64"
@@ -29,4 +32,7 @@ sphinx:
 # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
 python:
    install:
-   - requirements: docs/requirements.txt
+   - method: pip
+     path: .
+     extra_requirements:
+       - docs

README.md

@@ -1,11 +1,17 @@
-# Reinforcement Learning based Shape Optimization
+# Reinforcement Learning based Shape Optimization (ReLeSO)
 
-This repository holds a Library/Framework written by Clemens Fricke for
+[![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/tataratat/releso/pypi_upload)](https://github.com/tataratat/releso)
+[![Read the docs](https://readthedocs.org/projects/releso/badge/?version=latest)](https://releso.readthedocs.io/en/latest/?badge=latest)
+[![PyPI - Version](https://img.shields.io/pypi/v/releso)](https://pypi.org/project/releso/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/releso)](https://pypi.org/project/releso/)
+[![PyPI - License](https://img.shields.io/pypi/l/releso)](https://github.com/tataratat/releso/blob/main/LICENSE)
+
+Releso is a Library/Framework for
 Reinforcement Learning based Shape Optimization. Please look into the
 Documentation for information on how it works. The instruction on how the
 documentation can be built is given below as well as the instruction on how the
-package can be installed. It is currently not available from `pip`, this might
-come in the future.
+package can be installed.  
+Alternatively, it can be installed from `pip` via `pip install releso`.
 
 
 Documentation generation
@@ -23,7 +29,7 @@ dependencies for building the documentation.
 ``` console
 (base) $ conda create -n sphinx python=3.9
 (base) $ conda activate sphinx
-(sphinx) $ pip install sphinx sphinx-rtd-theme
+(sphinx) $ pip install ".[docs]"
 ```
 
 The documentation is built by executing the following command inside the folder
@@ -41,7 +47,7 @@ This section covers the installation process of the framework and its
 prerequisites. The first thing to note is that with version 0.1.0 the strict
 dependency on `splinepy` is not present anymore. But if the
 geometry is to be parameterized by a Spline and the method of Free Form
-Deformation is to be used to deform a mesh, `splinepy` is
+Deformation is to be used to deform a mesh, `splinepy` is still
 necessary.
 
 Prerequisites
@@ -70,9 +76,6 @@ The packages can be installed via pip or conda with the following commands:
 (base) $ conda activate releso
 (releso) $ pip install stable-baselines3 hjson
 ```
-> The quotation marks are necessary for some command lines like `zsh`. But from
-testing, `bash` is also ok if you use them even though they are not necessary.
-
 
 If the spline-based shape optimization functionality is needed, the package
 ``splinepy`` is needed. Please visit
@@ -104,5 +107,5 @@ running the command below in the main repository folder.
 **Development**
 
 ``` console
-(releso) $ pip install -e .
+(releso) $ pip install -e "dev."
 ```

docs/Makefile

@@ -17,4 +17,6 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
+	python ../schema.py
+	mv schema.json ../
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/source/conf.py

@@ -12,11 +12,12 @@
 
 
 """
-import ast
+from pydantic import BaseModel
+from sphinx.ext.napoleon import _skip_member
 
-with open("../../releso/__version__.py") as f:
-    version = ast.literal_eval(f.read().strip().split("=")[-1])
+from releso.__version__ import version
 
+# sys.path.insert(0, str(releso_dir / "util"))
 # -- Project information -----------------------------------------------------
 
 project = "ReLeSO"
@@ -37,28 +38,23 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
+    "sphinx-jsonschema",
     # 'sphinxcontrib.autodoc_pydantic'
 ]
 autosummary_generate = True  # Turn on sphinx.ext.autosummary
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
-# autodoc_mock_imports = [
-#     "pydantic",
-#     "tensorboard",
-#     "hjson",
-#     "gym",
-#     "stable_baselines3",
-#     "pandas",
-#     "gustaf",
-#     "numpy",
-#     "vedo",
-#     "matplotlib",
-#     "imageio",
-#     "torchvision",
-#     "torch",
-# ]
+autodoc_mock_imports = [
+    "gymnasium",
+    "gustaf",
+    "vedo",
+    "matplotlib",
+    "imageio",
+    "torchvision",
+    "splinepy",
+]
 # show type hints in doc body instead of signature
-# autodoc_typehints = 'description'
+# autodoc_typehints = "both"
 # get docstring from class level and init simultaneously
 # autoclass_content = 'instance'
 
@@ -67,8 +63,8 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
-autodoc_pydantic_model_show_json = True
-autodoc_pydantic_settings_show_json = False
+# autodoc_pydantic_model_show_json = True
+# autodoc_pydantic_settings_show_json = False
 
 # -- Options for HTML output ----------------------------------------------
 
@@ -83,3 +79,51 @@
 # 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"]
+
+
+# static variable needs only be initialized once
+pydantic_functions = list(BaseModel.__dict__)
+
+
+def skip(app, what, name, obj, would_skip, options):
+    """Check if member should be shown in the documentation.
+
+    A little complication, is that if a `autodoc-skip-member` event is
+    registered if the `napoleon` extension is enabled, it will be called
+    instead of the default skip member function. (It is not additive)
+    So I am calling this function from this new skip function so that I do
+    not have to reimplement the same functionality.
+
+    Additional members that are skipped are pydantic functions that are
+    inherited and functions that start with `check_` or `validate_`. These
+    functions are used as validators for the data in this package and should
+    normally not be called from user code.
+
+    Args:
+        app (sphinx.application.Sphinx): Sphinx application.
+        what (str): Type of the object.
+        name (str): Name of the Object.
+        obj (Any): The object itself.
+        would_skip (bool): Decision of the object should be skipped from
+            previous checks.
+        options (Any): Options.
+
+    Returns:
+        bool: Whether or not to skip the object.
+    """
+    if would_skip := _skip_member(app, what, name, obj, would_skip, options):
+        return would_skip
+    if name in pydantic_functions:
+        return True
+    if name.startswith(("check_", "validate_")):
+        return True
+    # return would_skip
+
+
+def setup(app):
+    """Method that is called from sphinx to load user code for the docs build.
+
+    Args:
+        app (sphinx.application.Sphinx): Sphinx application.
+    """
+    app.connect("autodoc-skip-member", skip)

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,44 @@
    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/tataratat/releso/pypi_upload
+   :target: https://github.com/tataratat/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/tataratat/releso/blob/main/LICENSE
+    :alt: PyPI - License
+
+**ReLeSO** stands for ``Reinforcement Learning based Shape Optimization`` and is a Python framework combining a spline-based 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 optimization steps towards better learning [Fricke2023]_. In the last paper we compare different agents and the two types of RL-based shape optimization that this framework implements, namely 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 +62,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: