Add template for Sphinx based documentation (#13)

* Add template for Sphinx based documentation.

* Add comments to Dockerfile

* Remove install_engine.sh

* Update pyproject.toml

* Update README.md

Author: domgz

Dockerfile

@@ -1,3 +1,7 @@
+# This is a template Dockerfile in case you want to offer your users the
+# possibility to run your wrapper using Docker (for example, this may be handy
+# when the installation of a required simulation engine is complicated)
+
 FROM python:3.10
 LABEL org.opencontainers.image.authors="you@domain.org"
 
@@ -14,5 +18,6 @@ RUN echo "Install the engine here"
 # Install your package. Dependencies, including `simphony-osp` will be
 # automatically installed.
 RUN pip install .
-# Maybe you also need to install an ontology
+# Maybe you also need to install a specific ontology that your wrapper makes
+# use of (like `package_name/ontology.yml` for this prototype wrapper example).
 RUN pico install some_ontology_maybe.yml

README.md

@@ -6,9 +6,11 @@ SimPhoNy. **Before you start**, please have a look at the
 (in particular the 
 [wrapper development section](https://simphony.readthedocs.io/en/v4.0.0rc4/developers/wrappers.html)).
 
-You may clone this repository and use it as a template to create your own
-wrapper. It provides project configuration files, a folder structure and even a 
-minimalistic implementation of a wrapper.
+Clone this repository to use it as a template to create your own
+wrapper. It provides project configuration files, a folder structure, an 
+example of a minimalistic implementation of a wrapper, tests, and a documentation 
+template. While writing the documentation, you can show it on your web browser
+using [sphinx-autobuild](https://github.com/executablebooks/sphinx-autobuild).
 
 The version number of this project matches the number of the 
 [`simphony-osp`](https://pypi.org/project/simphony-osp/4.0.0rc4/) package 
@@ -17,7 +19,8 @@ version for which it was last updated. As SimPhoNy follows the
 prototype should be compatible with the newest version of SimPhoNy as long as 
 their major version numbers match.
 
-**Do not forget to choose a license and change the file `LICENSE.md` before 
-publishing your wrapper!**
+**Do not forget to choose a license and change the license information in the
+files `LICENSE.md`, `pyproject.toml` and `docs/conf.py` before publishing your 
+wrapper!**
 
 *Contact*: [Material Informatics team at Fraunhofer IWM](mailto:simphony@iwm.fraunhofer.de)

docs/conf.py

@@ -0,0 +1,49 @@
+"""Configuration file for the Sphinx documentation builder."""
+
+# --- Project information --- #
+
+project = "MyWrapperName"
+copyright = "2022, Materials Informatics team at Fraunhofer IWM"
+author = "Materials Informatics team at Fraunhofer IWM"
+
+
+# --- General configuration --- #
+
+extensions = [
+    "myst_parser",  # Markdown support
+    "sphinx.ext.autodoc",  # API reference
+    "sphinx.ext.napoleon",  # Google and NumPy style docstrings support
+    "sphinx.ext.viewcode",  # Link to source in API reference
+    "sphinx_copybutton",  # Copy button for code blocks
+    "nbsphinx",  # Jupyter notebook support
+    "IPython.sphinxext.ipython_console_highlighting",  # Syntax highlighting
+    "sphinx.ext.autosectionlabel",  # Auto-generate section labels.
+    "sphinx_panels",  # Show panels in a grid layout or as drop-downs
+]
+
+master_doc = "index"
+
+myst_heading_anchors = 5
+
+suppress_warnings = ["autosectionlabel.*"]
+exclude_patterns = ["**.ipynb_checkpoints"]
+nbsphinx_allow_errors = False
+
+
+# --- HTML output options --- #
+html_theme = "sphinx_book_theme"
+html_favicon = "static/favicon.png"  # Noto Sans open book emoji
+html_logo = "static/logo.png"
+html_theme_options = {
+    "github_url": "https://github.com/my_organization/my_wrapper",
+    "repository_url": "https://github.com/my_organization/my_wrapper",
+    "use_repository_button": True,
+    "repository_branch": "main",
+    "path_to_docs": "docs",
+    "logo_only": True,
+    "show_navbar_depth": 1,
+}
+
+
+html_static_path = ["static"]
+html_css_files = ["custom.css"]

docs/index.md

@@ -0,0 +1,24 @@
+# MyWrapperName
+
+```{note}
+⚠️ This is a template for the documentation of your wrapper. Modify it to suit
+your needs.
+```
+
+MyWrapperName is a SimPhoNy wrapper that enables the use of MySimualtionEngine 
+on the SimPhoNy Open Simulation Platform.
+
+MySimulationEngine is a sample molecular dynamics simulation engine. Given a 
+collection of atoms, their initial positions, and their velocities, it can 
+calculate their future positions, under the assumption that atoms do not exert 
+any kind of force among themselves neither there are any external forces acting
+on them.
+
+```{toctree}
+:hidden: true
+:maxdepth: 2
+
+installation
+usage
+License <https://example.org/my_license_file_can_be_githubs_one>
+```

docs/installation.md

@@ -0,0 +1,31 @@
+# Installation
+
+This wrapper requires a working installation of MySimulationEngine. Follow 
+these steps or check [this documentation to install](https://example.org) 
+MySimulationEngine.
+
+The next step is to install the wrapper itself. MyWrapperName is available on 
+PyPI, so it can be installed using the `pip` package manager.
+
+```shell
+pip install package-name
+```
+
+Finally, the wrapper requires MyOntology to operate. Download the 
+[ontology file](https://example.org/ontology_file.ttl) and 
+[ontology package](https://example.org/ontology_package.yml), then install the
+latter using the command below.
+
+```shell
+pico install ontology.yml
+```
+
+## Advanced users
+
+If you are a developer or an advanced user, you might be interested in 
+installing MyWrapperName from source.
+
+```shell
+git clone https://github.com/my_organization/my_wrapper
+pip install ./my_wrapper
+```

docs/static/custom.css

@@ -0,0 +1,25 @@
+.caption-text,
+h1,
+h2,
+h3,
+h4 {
+  color: #6580a1 !important;
+}
+
+.btn-outline-primary {
+  border-color: #6580a1 !important;
+}
+
+.btn-outline-primary:hover {
+  background-color: #6580a1 !important;
+  color: azure !important;
+}
+
+@media (min-width: 1200px) {
+  .container-xl {
+    max-width: 1550px;
+  }
+  #site-navigation {
+    max-width: 20%;
+  }
+}

docs/static/favicon.png

@@ -0,0 +1,66 @@
+# Usage
+
+Given a collection of atoms, their initial positions, and their velocities,
+MyWrapperName uses MySimulationEngine to calculate their future positions, 
+under the assumption that atoms do not exert any kind of force among themselves
+neither there are any external forces acting on them.
+
+To use MyWrapperName, start by importing it from the `simphony_osp.wrappers` 
+module, as well as by importing the `ontology_namespace` namespace.
+
+```python
+from simphony_osp.namespaces import ontology_namespace
+from simphony_osp.wrappers import SimulationWrapper
+```
+
+The next step is to call `SimulationWrapper` to create a SimPhoNy session
+
+```python
+session = SimulationWrapper()
+session.locked = True  # prevent session from closing after with statement
+```
+
+and populate it with your input data.
+
+```python
+with session:
+    for i in range(3):
+        atom = ontology_namespace.Atom()
+        atom[ontology_namespace.hasPart] = {
+            ontology_namespace.Position(value=[i, i, i], unit="m"),
+            ontology_namespace.Velocity(value=[i, -i, i], unit="m/s"),
+        }
+```        
+
+MyWrapperName uses individuals belonging to classes from MyOntology to 
+represent atoms, their positions and velocities. MyWrapperName expects to find
+the following pattern in the session's knowledge graph. 
+
+<figure style="display: table; text-align:center; margin-left: auto; margin-right:auto">
+
+![Sample linked data](./static/graph_pattern.drawio.svg)
+
+<figcaption style="display: table-caption; caption-side: bottom; text-align:center">
+
+_Pattern that MyWrapperName interprets in the session's knowledge graph in 
+order to recognize the atoms, their positions and their velocities._
+
+</figcaption>
+
+</figure>
+
+Finally, use SimPhoNy's `compute` command to run the simulation, optionally 
+specifying the number of time steps to consider in seconds (defaults to `1`). 
+Negative values can be provided in order to run the simulation backwards in 
+time.
+
+```python
+session.compute()
+# session.compute(time_steps=5)
+```
+
+After running the simulation, all the same atom, position and velocity ontology
+individuals will still be available in the session, but their positions will 
+have changed. As there are no forces acting on the atoms, their velocities 
+will remain constant.
+