(PR #69) Add RTD documentation

* Initialize environment for documentation
* Set up documentation structure
* Write installation guide
* Update permissions
* Rename `docs/source/tutorials` to `docs/source/tutorial`
* Move `BIG-MAP App Store` link to `conf.py`
* Write tutorial
* Write development guide
* Update author list in `setup.cfg`

.readthedocs.yaml

@@ -0,0 +1,28 @@
+---
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version 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/source/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+# - pdf
+# - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+ install:
+ - requirements: docs/requirements.txt

docs/Makefile

@@ -0,0 +1,23 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS ?=
+SPHINXBUILD ?= sphinx-build
+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
+
+# 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)
+
+rebuild:
+ @ make -s clean html

docs/requirements.in

@@ -0,0 +1,2 @@
+sphinx-design==0.4.1
+pydata-sphinx-theme==0.13.3

docs/requirements.txt

@@ -0,0 +1,80 @@
+#
+# This file is autogenerated by pip-compile with python 3.9
+# To update, run:
+#
+# pip-compile docs/requirements.in
+#
+accessible-pygments==0.0.4
+ # via pydata-sphinx-theme
+alabaster==0.7.13
+ # via sphinx
+babel==2.14.0
+ # via
+ # pydata-sphinx-theme
+ # sphinx
+beautifulsoup4==4.12.2
+ # via pydata-sphinx-theme
+certifi==2023.11.17
+ # via requests
+charset-normalizer==3.3.2
+ # via requests
+docutils==0.19
+ # via
+ # pydata-sphinx-theme
+ # sphinx
+idna==3.6
+ # via requests
+imagesize==1.4.1
+ # via sphinx
+importlib-metadata==7.0.1
+ # via sphinx
+jinja2==3.1.2
+ # via sphinx
+markupsafe==2.1.3
+ # via jinja2
+packaging==23.2
+ # via
+ # pydata-sphinx-theme
+ # sphinx
+pydata-sphinx-theme==0.13.3
+ # via -r docs/requirements.in
+pygments==2.17.2
+ # via
+ # accessible-pygments
+ # pydata-sphinx-theme
+ # sphinx
+requests==2.31.0
+ # via sphinx
+snowballstemmer==2.2.0
+ # via sphinx
+soupsieve==2.5
+ # via beautifulsoup4
+sphinx==6.2.1
+ # via
+ # pydata-sphinx-theme
+ # sphinx-design
+ # sphinxcontrib-applehelp
+ # sphinxcontrib-devhelp
+ # sphinxcontrib-htmlhelp
+ # sphinxcontrib-qthelp
+ # sphinxcontrib-serializinghtml
+sphinx-design==0.4.1
+ # via -r docs/requirements.in
+sphinxcontrib-applehelp==1.0.7
+ # via sphinx
+sphinxcontrib-devhelp==1.0.5
+ # via sphinx
+sphinxcontrib-htmlhelp==2.0.4
+ # via sphinx
+sphinxcontrib-jsmath==1.0.1
+ # via sphinx
+sphinxcontrib-qthelp==1.0.6
+ # via sphinx
+sphinxcontrib-serializinghtml==1.1.9
+ # via sphinx
+typing-extensions==4.9.0
+ # via pydata-sphinx-theme
+urllib3==2.1.0
+ # via requests
+zipp==3.17.0
+ # via importlib-metadata

docs/source/_static/examples/example.specs.csv

@@ -0,0 +1,2 @@
+Battery_Number;Rack_Position;Separator;Electrolyte;Electrolyte Position;Electrolyte Amount;Anode Position;Anode Type;Anode Diameter;Anode Weight;Anode Current Collector Weight (mg);Anode AM Content;Anode AM Weight (mg);Anode Practical Capacity (mAh/g);Anode Capacity (mAh);Cathode Position;Cathode Type;Cathode Diameter (mm);Cathode Weight (mg);Cathode Current Collector Weight (mg);Cathode AM Content;Cathode AM Weight (mg);Cathode Practical Capacity (mAh/g);Cathode Capacity (mAh);Target N:P Ratio;Actual N:P Ratio;Casing Type;Separator Diameter (mm);Spacer (mm);Comments;Barcode;Subbatch
+1;1;Whatman;1M LiPF6;1;100;28;Graphite;15;27.78;10;0;0;355;0;33;NMC622;14;17.1;8;0;0;160;0;1.2;-;2032;16;1;-;Barcode Not Read;0

docs/source/conf.py

@@ -0,0 +1,93 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Imports -----------------------------------------------------------------
+
+import time
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "AiiDAlab-Aurora"
+author = "Edan Bainglass"
+release = "0.11.1"
+
+copyright_first_year = "2021"
+
+copyright_owners = (
+ "Loris Ercole ([email protected])",
+ "Francisco F. Ramirez ([email protected])",
+ "Edan Bainglass ([email protected])",
+ "Giovanni Pizzi ([email protected])",
+)
+
+current_year = str(time.localtime().tm_year)
+copyright_year_string = current_year \
+ if current_year == copyright_first_year \
+ else f"{copyright_first_year}-{current_year}"
+
+copyright = f"{copyright_year_string}. All rights reserved"
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+show_authors = True
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "sphinx"
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+ "sphinx_design",
+]
+
+# The pydata-sphinx-theme already loads the bootstrap css.
+panels_add_bootstrap_css = False
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# The suffix of source filenames.
+source_suffix = ".rst"
+
+# The master toctree document.
+# ~ master_doc = 'index'
+master_doc = "index"
+
+# 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 = []
+
+# -- 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"
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+html_logo = "_static/images/full_logo.svg"
+
+# 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"]
+
+# If true, links to the reST sources are added to the pages.
+html_show_sourcelink = False
+
+# Define common links
+rst_epilog = """
+.. _AiiDA: https://www.aiida.net
+.. _AiiDAlab: https://www.aiidalab.net/
+.. _tomato: https://dgbowl.github.io/tomato/master/index.html
+.. _BIG-MAP App Store: https://big-map.github.io/big-map-registry/apps/aiidalab-aurora.html
+"""

docs/source/development/index.rst

@@ -0,0 +1,80 @@
+.. _development:
+
+Development Guide
+#################
+
+.. note::
+
+ If you have yet to do so, we recommend you first check out the :ref:`tutorial <tutorial>` to learn the basics of using the app.
+
+Aurora is open-source and as such, welcomes community contribution. To contribute to the development of the Aurora ecosystem, we recommend following these steps:
+
+#. Fork the plugin and app repositories
+
+ * plugin: ``https://github.com/epfl-theos/aiida-aurora.git``
+ * app: ``https://github.com/epfl-theos/aiidalab-aurora.git``
+
+ .. important::
+
+ Requires a GitHub account.
+
+#. Install the app **locally** (see :ref:`installation guide <installation>`)
+
+ a. Follow the local Docker-based installation guide of AiiDAlab
+ b. Open AiiDAlab in the browser
+ c. Open the AiiDAlab terminal and run the following code:
+
+ .. code::
+
+ mkdir ~/src
+
+ cd ~/src
+ git clone https://github.com/<your-github-username>/aiida-aurora.git
+ cd aiida-aurora
+ pip install -e .[testing,docs]
+
+ cd ~/apps
+ git clone https://github.com/<your-github-username>/aiidalab-aurora.git aurora
+ cd aurora
+ pip install -e .[docs]
+
+ mkdir ~/aiida_run
+
+#. Install *tomato* **locally** - run ``pip install tomato`` from the AiiDAlab terminal
+#. Open a separate terminal and run ``tomato -vv`` to start the *tomato* server
+#. From the main terminal, run ``ketchup status`` to verify that the server is up
+#. Set up AiiDA by running the following from terminal: (see :ref:`aiida setup <aiida_setup>` for more information)
+
+ .. code::
+
+ verdi computer setup \
+ --description "localhost running the tomato scheduler"
+ --label "localhost"
+ --hostname "localhost"
+ --transport "core.local"
+ --scheduler "tomato"
+ --work_dir "/home/jovyan/aiida_run/"
+ --mpirun_command "mpirun -np {tot_num_mpiprocs}"
+ --mpiprocs_per_machine 1
+ --shebang "#!/bin/bash"
+ --prepend_text ""
+ --append_text ""
+
+ verdi computer configure core.local \
+ --safe_interval: 0.0
+ --use_login_shell: true
+
+ verdi code create \
+ --label "ketchup-local"
+ --computer "localhost"
+ --description "ketchup submit"
+ --input_plugin "aurora.cycler"
+ --on_computer true
+ --remote_abs_path "/opt/conda/bin/ketchup"
+ --use_double_quotes False
+ --prepend_text ""
+ --append_text ""
+
+----
+
+Once you finish applying, committing, and pushing your changes, please create a PR to the `epfl-theos` accounts and await review.