WIP Add documentation

.readthedocs.yaml

+# .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: "mambaforge-4.10"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/source/conf.py
+
+# Optionally declare the Python requirements required to build your docs
+conda:
+  environment: environment.yml
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

README.md

 # The CADET-Research Data Management toolbox
 
-## Getting started
-
-### Installation
-
-CADET-RDM can be installed using
-
-```pip install cadet-rdm```
-
-### Initialize Project Repository
-
-Create a new project repository or convert an existing repository into a CADET-RDM repo:
-
-```bash
-cadet-rdm initialize-repo <path-to-repo>
-```
-
-or from python
-
-```python
-from cadetrdm import initialize_repo
-
-initialize_repo(path_to_repo)
-```
-
-The `output_folder_name` can be given optionally. It defaults to `output`.
-
-## Use CADET-RDM in Python
-
-### Tracking Results
-
-```python
-from cadetrdm import ProjectRepo
-
-"""
-Your imports and function declarations
-e.g. generate_data(), write_data_to_file(), analyse_data() and plot_analysis_results()
-"""
-
-if __name__ == '__main__':
-    # Instantiate CADET-RDM ProjectRepo handler
-    repo = ProjectRepo()
-
-    # If you've made changes to the code, commit the changes
-    repo.commit("Add code to generate and analyse example data")
-
-    # Everything written to the output_folder within this context manager gets tracked
-    # The method repo.output_data() generates full paths to within your output_folder
-    with repo.track_results(results_commit_message="Generate and analyse example data"):
-        data = generate_data()
-        output_filepath = repo.output_data(sub_path="raw_data/data.csv")
-        write_data_to_file(data, output_filepath)
-
-        analysis_results = analyse_data(data)
-        figure_path = repo.output_data("analysis/regression.png")
-        plot_analysis_results(analysis_results, figure_path)
-
-```
-
-### Sharing Results
-
-To share your project code and results with others, you need to create remote repositories on e.g.
-[GitHub](https://github.com/) or GitLab. You need to create a remote for both the _project_ repo and the
-_results_ repo.
-
-Once created, the remotes need to be added to the local repositories.
-
-```bash
-cadet-rdm add-remote-to-repo git@<my_git_server.foo>:<project>.git
-cadet-rdm --path_to_repo output add-remote-to-repo git@<my_git_server.foo>:<project>_output.git
-```
-
-or in Python:
-
-```python
-repo = ProjectRepo()
-repo.add_remote("git@<my_git_server.foo>:<project>.git")
-repo.output_repo.add_remote("git@<my_git_server.foo>:<project>_output.git")
-```
-
-Once remotes are configured, you can push all changes to the project repo and the results repos with the
-command
-
-```python
-# push all changes to the Project and Output repositories with one command:
-repo.push()
-```
-
-### Re-using results from previous iterations
-
-Each result stored with CADET-RDM is given a unique branch name, formatted as:
-`<timestamp>_<output_folder>_"from"_<active_project_branch>_<project_repo_hash[:7]>`
-
-With this branch name, previously generated data can be loaded in as input data for
-further calculations.
-
-```python
-cached_array_path = repo.input_data(branch_name=branch_name, source_file_path="raw_data/data.csv")
-```
-
-Alternatively, using the auto-generated cache of previous results, CADET-RDM can infer
-the correct branch name from the path to the file within the cache
-
-```python
-cached_array_path = repo.input_data(source_file_path="output_cached/<branch_name>/raw_data/data.csv")
-```
-
-## Use CADET RDM from the CLI
-
-### Executing scripts
-
-You can execute python files or arbitray commands using the CLI:
-
-```bash
-cd path/to/your/project
-cadet-rdm run-python-file <path/to/file> "commit message for the results"
-cadet-rdm run-command "command as it would be run" "commit message for the results"
-```
-
-For the run-command option, the command must be given in quotes, so:
-
-```bash
-cadet-rdm run-command "python example_file.py" "commit message for the results"
-```
-
-
-### Using results from another repository
-
-You can load in results from another repository to use in your project using the CLI:
-
-```bash
-cd path/to/your/project
-cadet-rdm import-remote-repo <URL> <branch_name>
-cadet-rdm import-remote-repo <URL> <branch_name> --target_repo_location <path/to/where/you/want/it>
-```
-
-This will store the URL, branch_name and location in the .cadet-rdm-cache.json file, like this:
-
-```json
-{
-  "__example/path/to/repo__": {
-    "source_repo_location": "git@jugit.fz-juelich.de:IBG-1/ModSim/cadet/agile_cadet_rdm_presentation_output.git",
-    "branch_name": "output_from_master_3910c84_2023-10-25_00-17-23",
-    "commit_hash": "6e3c26527999036e9490d2d86251258fe81d46dc"
-  }
-}
-```
-
-You can use this file to load the remote repositories based on the cache.json with
-
-```bash
-cadet-rdm fill-data-from-cadet-rdm-json
-```
-
-### Cloning from remote
-
-You should use `cadet-rdm clone` instead of `git clone` to clone the repo to a new location.
-
-```bash
-cadet-rdm clone <URL> <path/to/repo>
-```

cadetrdm/cli_integration.py

@@ -116,3 +116,9 @@ def print_output_log():
     # ToDo: test if Project or Output repo
     repo = ProjectRepo(".")
     repo.print_output_log()
+
+
+@cli.command(help="Push all changes to the project and output repositories.")
+def push():
+    repo = ProjectRepo(".")
+    repo.push(push_all=True)

docs/Makefile

+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = CADET-RDM
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile html clean
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+html:
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+

docs/README.md

+# CADET-RDM Documentation
+
+To build the documentation locally, install sphinx and other dependencies by running
+
+```
+pip install -e .[docs]
+```
+from the CADET-RDM root directory.
+
+Then, in the `docs` folder run:
+
+```
+sphinx-build -b html source build
+```
+
+The output is in the `build` directory and can be opened with any browser.

docs/source/bibliography.md

+```{eval-rst}
+.. only:: html 
+
+  Bibliography
+  ============
+
+```
+
+```{bibliography} ./references.bib
+:style: unsrt
+```
+

docs/source/conf.py

+# Configuration file for the Sphinx documentation builder.
+
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath('../..'))
+from datetime import date
+
+# -- Project information -----------------------------------------------------
+
+project = 'CADET-RDM'
+copyright = f'2023-{date.today().year}'
+author = 'IBG-1 ModSim Group'
+
+import cadetrdm
+
+version = cadetrdm.__version__
+release = cadetrdm.__version__.replace("_", "")
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+
+# Extensions
+extensions = []
+
+## MyST-NB
+extensions.append("myst_nb")
+nb_execution_mode = "cache"
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.ipynb': 'myst-nb',
+    '.myst': 'myst-nb',
+    '.md': 'myst-nb',
+}
+
+## Numpydoc
+extensions.append("numpydoc")
+numpydoc_class_members_toctree = False
+
+## Autodoc
+extensions.append("sphinx.ext.autodoc")
+
+## Autosummary
+extensions.append("sphinx.ext.autosummary")
+autosummary_generate = True
+
+## Intersphinx mapping
+extensions.append("sphinx.ext.intersphinx")
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "matplotlib": ("https://matplotlib.org/stable", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/reference", None),
+    "cadet": ("https://cadet.github.io/master/", None),
+}
+
+## To do
+extensions.append("sphinx.ext.todo")
+todo_include_todos = True
+
+## Viewcode
+extensions.append("sphinx.ext.viewcode")
+
+## Copy Button
+extensions.append("sphinx_copybutton")
+
+## BibTeX
+extensions.append("sphinxcontrib.bibtex")
+bibtex_bibfiles = ['references.bib']
+
+# -- Internationalization ------------------------------------------------
+# specifying the natural language populates some key tags
+language = "en"
+
+# ReadTheDocs has its own way of generating sitemaps, etc.
+if not os.environ.get("READTHEDOCS"):
+    extensions += ["sphinx_sitemap"]
+
+    # -- Sitemap -------------------------------------------------------------
+    html_baseurl = os.environ.get("SITEMAP_URL_BASE", "http://127.0.0.1:8000/")
+    sitemap_locales = [None]
+    sitemap_url_scheme = "{link}"
+
+# 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"]
+
+# -- Extension options -------------------------------------------------------
+
+myst_enable_extensions = [
+    "dollarmath",
+    "amsmath",
+    "colon_fence",
+]
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.
+html_theme = "sphinx_book_theme"
+html_logo = "_static/logo.png"
+
+html_theme_options = {
+    "show_toc_level": 2,
+    "use_download_button": True,
+    "repository_url": "https://jugit.fz-juelich.de/IBG-1/ModSim/cadet/CADET-RDM",
+    "repository_provider": "gitlab",
+    "use_repository_button": True,
+    "use_issues_button": False,
+}
+
+html_sidebars = {
+    "**": ["navbar-logo.html", "search-field.html", "sbt-sidebar-nav.html"]
+}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# 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"]

docs/source/index.md

+```{include} ../../README.md
+```
+
+```{toctree}
+:maxdepth: 2
+:caption: User guide
+:hidden:
+
+user_guide/installation
+user_guide/getting-started
+user_guide/CLI-interface
+user_guide/python-interface
+user_guide/jupyter-interface
+```
+
+
+```{toctree}
+:maxdepth: 2
+:caption: References
+:hidden:
+
+license
+bibliography
+```

docs/source/license.md

+(license)=
+# License
+
+```{literalinclude} ../../LICENSE
+:language: none
+```

docs/source/references.bib

+@Article{Bailly1982,
+  author    = {Bailly, Michel and Tondeur, Daniel},
+  journal   = {Chemical Engineering Science},
+  title     = {Recycle Optimization in Non-Linear Productive Chromatography—{{I Mixing}} Recycle with Fresh Feed},
+  year      = {1982},
+  number    = {8},
+  pages     = {1199--1212},
+  volume    = {37},
+  annote    = {MR-SSR},
+}
+
+@Article{Dienstbier2020,
+  author   = {Dienstbier, Jana and Schmölder, Johannes and Burlacu, Robert and Liers, Frauke and Kaspereit, Malte},
+  title    = {Global Optimization of Batch and Steady-State Recycling Chromatography Based on the Equilibrium Model},
+  doi      = {10.1016/j.compchemeng.2019.106687},
+  issn     = {0098-1354},
+  pages    = {106687},
+  url      = {http://www.sciencedirect.com/science/article/pii/S0098135419307409},
+  volume   = {135},
+  journal  = {Computers \& Chemical Engineering},
+  year     = {2020},
+}
+
+@Article{Heymann2022,
+  author   = {William Heymann and Juliane Glaser and Fabrice Schlegel and Will Johnson and Pablo Rolandi and Eric {von Lieres}},
+  title    = {Advanced score system and automated search strategies for parameter estimation in mechanistic chromatography modeling},
+  doi      = {https://doi.org/10.1016/j.chroma.2021.462693},
+  issn     = {0021-9673},
+  pages    = {462693},
+  url      = {https://www.sciencedirect.com/science/article/pii/S0021967321008153},
+  volume   = {1661},
+  journal  = {Journal of Chromatography A},
+  keywords = {Chromatography model, Parameter estimation, Score system},
+  year     = {2022},
+}
+
+@InCollection{Holmqvist2015,
+  author    = {Holmqvist, Anders and Magnusson, Fredrik and Nilsson, Bernt},
+  booktitle = {Computer {{Aided Chemical Engineering}}},
+  title     = {Dynamic {{Multi}}-{{Objective Optimization}} of {{Batch Chromatographic Separation Processes}}},
+  doi       = {10.1016/b978-0-444-63578-5.50131-6},
+  pages     = {815--820},
+  publisher = {{Elsevier}},
+  volume    = {37},
+  comment   = {(see Holmqvist2016 for objective function)},
+  file      = {:Holmqvist2015 - Dynamic Multi Objective Optimization of Batch Chromatographic Separation Processes.pdf:},
+  groups    = {Chrom. Process Design},
+  year      = {2015},
+}
+
+@Article{King1990,
+  author  = {King, D. Whitney and Kester, Dana R.},
+  title   = {A general approach for calculating polyprotic acid speciation and buffer capacity},
+  doi     = {10.1021/ed067p932},
+  number  = {11},
+  pages   = {932},
+  url     = {https://doi.org/10.1021/ed067p932},
+  volume  = {67},
+  journal = {Journal of Chemical Education},
+  year    = {1990},
+}
+
+@Article{Leweke2018,
+  author       = {Leweke, Samuel and von Lieres, Eric},
+  year         = {2018},
+  journal = {Computers \& Chemical Engineering},
+  title        = {Chromatography {{Analysis}} and {{Design Toolkit}} ({{CADET}})},
+  doi          = {10.1016/j.compchemeng.2018.02.025},
+  issn         = {0098-1354},
+  pages        = {274--294},
+  url          = {http://www.sciencedirect.com/science/article/pii/S0098135418300966},
+  volume       = {113},
+}
+
+@Book{Levenspiel1999,
+  author    = {Levenspiel, O.},
+  title     = {Chemical Reaction Engineering},
+  doi       = {10.1021/ie990488g},
+  isbn      = {978-0-471-25424-9},
+  publisher = {{Wiley}},
+  year      = {1999},
+}
+
+@InCollection{Powell1994,
+  author    = {Powell, M. J. D.},
+  booktitle = {Advances in {{Optimization}} and {{Numerical Analysis}}},
+  title     = {A {{Direct Search Optimization Method That Models}} the {{Objective}} and {{Constraint Functions}} by {{Linear Interpolation}}},
+  doi       = {10.1007/978-94-015-8330-5_4},
+  editor    = {Gomez, Susana and Hennart, Jean-Pierre},
+  isbn      = {978-90-481-4358-0 978-94-015-8330-5},
+  pages     = {51--67},
+  publisher = {{Springer Netherlands}},
+  series    = {Mathematics and Its {{Applications}}},
+  urldate   = {2020-05-20},
+  address   = {{Dordrecht}},
+  langid    = {english},
+  year      = {1994},
+}
+
+@Article{pymoo2020,
+  author  = {J. {Blank} and K. {Deb}},
+  title   = {pymoo: Multi-Objective Optimization in Python},
+  pages   = {89497-89509},
+  volume  = {8},
+  journal = {IEEE Access},
+  year    = {2020},
+}
+
+@Article{Sainio2009,
+  author    = {Sainio, Tuomo and Kaspereit, Malte},
+  journal   = {Separation and Purification Technology},
+  title     = {Analysis of Steady State Recycling Chromatography Using Equilibrium Theory},
+  year      = {2009},
+  number    = {1},
+  pages     = {9--18},
+  volume    = {66},
+  doi       = {10.1016/j.seppur.2008.12.005},
+}
+
+@Book{SchmidtTraub2020,
+  author    = {Schmidt-Traub, H. and Schulte, M. and Seidel-Morgenstern, A.},
+  title     = {Preparative {{Chromatography}}},
+  isbn      = {9783527816316},
+  publisher = {{Wiley}},
+  file      = {:SchmidtTraub2020 - Preparative Chromatography.pdf:PDF},
+  groups    = {Chrom. Fundamentals},
+  year      = {2020},
+}
+
+@Article{SciPyContributors2020,
+  author       = {{SciPy 1.0 Contributors} and Virtanen, Pauli and Gommers, Ralf and Oliphant, Travis E. and Haberland, Matt and Reddy, Tyler and Cournapeau, David and Burovski, Evgeni and Peterson, Pearu and Weckesser, Warren and Bright, Jonathan and van der Walt, Stéfan J. and Brett, Matthew and Wilson, Joshua and Millman, K. Jarrod and Mayorov, Nikolay and Nelson, Andrew R. J. and Jones, Eric and Kern, Robert and Larson, Eric and Carey, C J and Polat, İlhan and Feng, Yu and Moore, Eric W. and VanderPlas, Jake and Laxalde, Denis and Perktold, Josef and Cimrman, Robert and Henriksen, Ian and Quintero, E. A. and Harris, Charles R. and Archibald, Anne M. and Ribeiro, Antônio H. and Pedregosa, Fabian and van Mulbregt, Paul},
+  title        = {{{SciPy}} 1.0: Fundamental Algorithms for Scientific Computing in {{Python}}},
+  doi          = {10.1038/s41592-019-0686-2},
+  issn         = {1548-7091, 1548-7105},
+  number       = {3},
+  pages        = {261--272},
+  url          = {http://www.nature.com/articles/s41592-019-0686-2},
+  urldate      = {2020-05-20},
+  volume       = {17},
+  file         = {:SciPy1.0Contributors2020 - SciPy 1.0_ Fundamental Algorithms for Scientific Computing in Python.pdf:},
+  journal      = {Nature Methods},
+  keywords     = {python},
+  langid       = {english},
+  month        = mar,
+  options      = {useprefix=true},
+  shortjournal = {Nat Methods},
+  shorttitle   = {{{SciPy}} 1.0},
+  year         = {2020},
+}
+
+@Article{Schmoelder2020,
+  author  = {Schmölder, Johannes and Kaspereit, Malte},
+  title   = {A {{Modular Framework}} for the {{Modelling}} and {{Optimization}} of {{Advanced Chromatographic Processes}}},
+  doi     = {10.3390/pr8010065},
+  number  = {1},
+  pages   = {65},
+  volume  = {8},
+  journal = {Processes},
+  year    = {2020},
+}
+
+@Article{Seada2016,
+  author={Seada, Haitham and Deb, Kalyanmoy},
+  journal={IEEE Transactions on Evolutionary Computation}, 
+  title={A Unified Evolutionary Optimization Procedure for Single, Multiple, and Many Objectives}, 
+  year={2016},
+  volume={20},
+  number={3},
+  pages={358-369},
+  doi={10.1109/TEVC.2015.2459718}
+}
+
+@Article{Shan2004,
+  author   = {Shan, Yichu and Seidel-Morgenstern, Andreas},
+  title    = {Analysis of the Isolation of a Target Component Using Multicomponent Isocratic Preparative Elution Chromatography},
+  doi      = {10.1016/j.chroma.2004.04.061},
+  number   = {1},
+  pages    = {53--62},
+  volume   = {1041},
+  journal  = {Journal of Chromatography A},
+  keywords = {fractionation},
+  year     = {2004},
+}
+
+@Article{Tobo2020,
+  author    = {Tobo, Yohannis Mitiku and Bartacek, Jan and Nopens, Ingmar},
+  title     = {Linking {CFD} and {Kinetic} {Models} in {Anaerobic} {Digestion} {Using} a {Compartmental} {Model} {Approach}},
+  doi       = {10.3390/pr8060703},
+  language  = {en},
+  number    = {6},
+  pages     = {703},
+  url       = {https://www.mdpi.com/2227-9717/8/6/703},
+  urldate   = {2020-11-20},
+  volume    = {8},
+  journal   = {Processes},
+  keywords  = {ADM1, CFD, CM, kinetics, non-Newtonian fluid, spatial variation},
+  month     = jun,
+  publisher = {Multidisciplinary Digital Publishing Institute},
+  timestamp = {2020-11-20},
+  year      = {2020},
+}

docs/source/user_guide/CLI-interface.md

+
+# CLI Interface
+
+## Initialize Project Repository
+
+Create a new project repository or convert an existing repository into a CADET-RDM repo:
+
+```bash
+cadet-rdm initialize-repo <path-to-repo>
+```
+
+
+The `output_folder_name` can be given optionally. It defaults to `output`.
+
+
+## Executing scripts
+
+You can execute python files or arbitray commands using the CLI:
+
+```bash
+cd path/to/your/project
+cadet-rdm run-python-file <path/to/file> "commit message for the results"
+cadet-rdm run-command "command as it would be run" "commit message for the results"
+```
+
+For the run-command option, the command must be given in quotes, so:
+
+```bash
+cadet-rdm run-command "python example_file.py" "commit message for the results"
+```
+
+
+## Using results from another repository
+
+You can load in results from another repository to use in your project using the CLI:
+
+```bash
+cd path/to/your/project
+cadet-rdm import-remote-repo <URL> <branch_name>
+cadet-rdm import-remote-repo <URL> <branch_name> --target_repo_location <path/to/where/you/want/it>
+```
+
+This will store the URL, branch_name and location in the .cadet-rdm-cache.json file, like this:
+
+```json
+{
+  "__example/path/to/repo__": {
+    "source_repo_location": "git@jugit.fz-juelich.de:IBG-1/ModSim/cadet/agile_cadet_rdm_presentation_output.git",
+    "branch_name": "output_from_master_3910c84_2023-10-25_00-17-23",
+    "commit_hash": "6e3c26527999036e9490d2d86251258fe81d46dc"
+  }
+}
+```
+
+You can use this file to load the remote repositories based on the cache.json with
+
+```bash
+cadet-rdm fill-data-from-cadet-rdm-json
+```
+
+## Cloning from remote
+
+You should use `cadet-rdm clone` instead of `git clone` to clone the repo to a new location.
+
+```bash
+cadet-rdm clone <URL> <path/to/repo>
+```
+
+
+## Sharing Results
+
+To share your project code and results with others, you need to create remote repositories on e.g.
+[GitHub](https://github.com/) or GitLab. You need to create a remote for both the _project_ repo and the
+_results_ repo.
+
+Once created, the remotes need to be added to the local repositories.
+
+```bash
+cadet-rdm add-remote-to-repo git@<my_git_server.foo>:<project>.git
+cadet-rdm --path_to_repo output add-remote-to-repo git@<my_git_server.foo>:<project>_output.git
+```
+
+Once remotes are configured, you can push all changes to the project repo and the results repos with the
+command
+
+```bash
+cadet-rdm push
+```

docs/source/user_guide/getting-started.md

+
+# Getting started
+
+## Initialize Project Repository
+
+Create a new project repository or convert an existing repository into a CADET-RDM repo:
+
+```bash
+cadet-rdm initialize-repo <path-to-repo>
+```
+
+or from python
+
+```python
+from cadetrdm import initialize_repo
+
+initialize_repo(path_to_repo)
+```
+
+The `output_folder_name` can be given optionally. It defaults to `output`.

docs/source/user_guide/installation.md

+
+# Installation
+
+CADET-RDM can be installed using
+
+```pip install cadet-rdm```
+

docs/source/user_guide/jupyter-interface.md

+
+# Jupyter interface
+
+The CADET-RDM Jupyter interface **only works** with [Jupyter Lab](https://jupyterlab.readthedocs.io/en/latest/), 
+and not with the old [Jupyter Notebook](https://jupyter-notebook.readthedocs.io/en/stable/notebook.html) interface
+at the moment.
+
+## General concepts
+
+### Jupytext
+
+Jupyter Notebooks are not well suited for version control with git, as the metadata and cell outputs are stored besides 
+the input code. This overwhelms the inspection of differences within commits and the comparisons between branches. 
+
+Therefore, the [jupytext](https://github.com/mwouts/jupytext) extension is used by default to convert `.ipynb` files
+into a `.py` files, with the markdown cells included as block comments. All `.ipynb` files are removed from git's 
+version control through the `.gitignore` file and only changes in the `.py` files are tracked. The `.py` files are
+automatically created and updated whenever a `.ipynb` file is saved. 
+
+Please ensure, that `juyptext` is working for you and that a `.py` file is created after saving your notebook, otherwise
+your code will not be version-controlled.
+
+### Reproducibility
+
+To ensure results from `.ipynb` files are perfectly reproducible, `CADET-RDM` does not allow for the tracking of
+results generated during live-coding usage. Therefore, before committing results, 
+all previous outputs are cleared and all cells
+are executed sequentially from top to bottom and then committed to the output repository.
+
+To maintain the link between Markdown annotation, code, and inline graphs, the final notebook is also saved as
+a `.html` webpage into the output folder for future inspection.
+
+## Tracking Results
+
+To use `CADET-RDM` from within an `.ipynb` file, please include this at the top of your file.
+
+```python
+from cadetrdm.repositories import JupyterInterfaceRepo
+
+repo = JupyterInterfaceRepo()
+```
+
+Then, at the end of your file, run:
+```python
+repo.commit_nb_output(
+    "path-to-the-current-notebook.ipynb",
+    results_commit_message="Results commit message"
+)
+```
+
+This will re-run the `.ipynb` file from the start, save a html version of the completed notebook into the output repo
+and commit all changes to the output repo.
+
+## Committing changes to your code
+
+You can commit all current changes to your code directly from Jupyter by running
+
+```python
+from cadetrdm.repositories import JupyterInterfaceRepo
+
+repo = JupyterInterfaceRepo()
+
+repo.commit("Commit message")
+```
+
+## Other workflows
+
+All other workflows function identically as described in the {ref}`python_interface` section.
\ No newline at end of file

docs/source/user_guide/python-interface.md

+(python_interface)=
+# Python interface
+
+## Tracking Results
+
+```python
+from cadetrdm import ProjectRepo
+
+"""
+Your imports and function declarations
+e.g. generate_data(), write_data_to_file(), analyse_data() and plot_analysis_results()
+"""
+
+if __name__ == '__main__':
+    # Instantiate CADET-RDM ProjectRepo handler
+    repo = ProjectRepo()
+
+    # If you've made changes to the code, commit the changes
+    repo.commit("Add code to generate and analyse example data")
+
+    # Everything written to the output_folder within this context manager gets tracked
+    # The method repo.output_data() generates full paths to within your output_folder
+    with repo.track_results(results_commit_message="Generate and analyse example data"):
+        data = generate_data()
+        output_filepath = repo.output_data(sub_path="raw_data/data.csv")
+        write_data_to_file(data, output_filepath)
+
+        analysis_results = analyse_data(data)
+        figure_path = repo.output_data("analysis/regression.png")
+        plot_analysis_results(analysis_results, figure_path)
+
+```
+
+## Sharing Results
+
+To share your project code and results with others, you need to create remote repositories on e.g.
+[GitHub](https://github.com/) or GitLab. You need to create a remote for both the _project_ repo and the
+_results_ repo.
+
+Once created, the remotes need to be added to the local repositories.
+
+```python
+repo = ProjectRepo()
+repo.add_remote("git@<my_git_server.foo>:<project>.git")
+repo.output_repo.add_remote("git@<my_git_server.foo>:<project>_output.git")
+```
+
+Once remotes are configured, you can push all changes to the project repo and the results repos with the
+command
+
+```python
+# push all changes to the Project and Output repositories with one command:
+repo.push()
+```
+
+## Re-using results from previous iterations
+
+Each result stored with CADET-RDM is given a unique branch name, formatted as:
+`<timestamp>_<output_folder>_"from"_<active_project_branch>_<project_repo_hash[:7]>`
+
+With this branch name, previously generated data can be loaded in as input data for
+further calculations.
+
+```python
+cached_array_path = repo.input_data(branch_name=branch_name, source_file_path="raw_data/data.csv")
+```
+
+Alternatively, using the auto-generated cache of previous results, CADET-RDM can infer
+the correct branch name from the path to the file within the cache
+
+```python
+cached_array_path = repo.input_data(source_file_path="output_cached/<branch_name>/raw_data/data.csv")
+```
+
+```json
+{
+  "__example/path/to/repo__": {
+    "source_repo_location": "git@jugit.fz-juelich.de:IBG-1/ModSim/cadet/agile_cadet_rdm_presentation_output.git",
+    "branch_name": "output_from_master_3910c84_2023-10-25_00-17-23",
+    "commit_hash": "6e3c26527999036e9490d2d86251258fe81d46dc"
+  }
+}
+```
+
+## Using results from another repository
+
+You can load in results from another repository to use in your project using the CLI:
+
+```python
+repo.import_remote_repo(source_repo_location="<URL>", source_repo_branch="<branch_name>")
+repo.import_remote_repo(source_repo_location="<URL>", source_repo_branch="<branch_name>",
+                        target_repo_location="<path/to/where/you/want/it>")
+```
+
+This will store the URL, branch_name and location in the .cadet-rdm-cache.json file, like this:
+
+```json
+{
+  "__example/path/to/repo__": {
+    "source_repo_location": "git@jugit.fz-juelich.de:IBG-1/ModSim/cadet/agile_cadet_rdm_presentation_output.git",
+    "branch_name": "output_from_master_3910c84_2023-10-25_00-17-23",
+    "commit_hash": "6e3c26527999036e9490d2d86251258fe81d46dc"
+  }
+}
+```
+
+You can use this file to load the remote repositories based on the cache.json with
+
+```python
+repo.fill_data_from_cadet_rdm_json()
+```
+
+## Cloning from remote
+
+You should use `cadetrdm.clone` instead of `git clone` to clone the repo to a new location.
+
+```python
+from cadetrdm import clone
+
+clone("<URL><path/to/repo>")
+```

environment.yml

+name: cadet-rdm
+channels:
+  - conda-forge
+dependencies:
+  - python=3.10

setup.cfg

@@ -46,6 +46,14 @@ testing =
     numpy
     build
 
+docs =
+    sphinx>=5.3.0
+    sphinxcontrib-bibtex>=2.5.0
+    sphinx_book_theme>=1.0.0
+    sphinx_copybutton>=0.5.1
+    sphinx-sitemap>=2.5.0
+    numpydoc>=1.5.0
+    myst-nb>=0.17.1
 
 [flake8]
 max_line_length = 88