yoavnash · Apr 9, 2021 · Apr 7, 2021 · Apr 7, 2021 · Apr 7, 2021 · Apr 7, 2021
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -12,7 +12,7 @@
 # -- Project information -----------------------------------------------------
 project = 'SimPhoNy'
 # Version is given in setuptools
-copyright = '2020, Materials Data Science and Informatics team at Fraunhofer IWM'
+copyright = '2021, Materials Data Science and Informatics Team at Fraunhofer IWM'
 author = 'Materials Data Science and Informatics team at Fraunhofer IWM'
 
 # -- General configuration ---------------------------------------------------
@@ -27,7 +27,8 @@
     'nbsphinx',  # Jupyter
     'IPython.sphinxext.ipython_console_highlighting',  # Jupyter - Syntax highlight workaround
     'sphinx.ext.autosectionlabel',  # Auto-generate section labels.
-    'sphinx-jsonschema'  # Generate JSON schema for serialized CUDS
+    'sphinx-jsonschema',  # Generate JSON schema for serialized CUDS
+    'sphinx_panels' # A sphinx extension for creating panels in a grid layout or as drop-downs
 ]
 
 master_doc = 'index'

diff --git a/docs/source/contact.md b/docs/source/contact.md
@@ -3,6 +3,6 @@ If you see something wrong, missing, or in need of clarification, you can direct
 create an issue in [here](https://github.com/simphony/docs/issues).
 
 Any other questions, issues or comments can be directed to [Pablo de Andres](mailto:pablo.de.andres@iwm.fraunhofer.de),
-[Matthias Urban](mailto:matthias.urban@iwm.fraunhofer.de)  and
+[Jose Manuel Dominguez](mailto:jose.manuel.dominguez@iwm.fraunhofer.de)  and
 [Yoav Nahshon](mailto:yoav.nahshon@iwm.fraunhofer.de)
-from the Materials Data Science and Informatics team, Fraunhofer IWM.
+from the Materials Data Science and Informatics Team, Fraunhofer IWM.
diff --git a/docs/source/motivation.md → docs/source/fundamentals.md b/docs/source/motivation.md → docs/source/fundamentals.md
@@ -1,5 +1,5 @@
-## Motivation
-In this section, we will present some of the main concepts SimPhoNy was created to tackle.
+## Fundamental concepts
+In this section we will present some of the main concepts behind SimPhoNy.
 ### Operability
 There is a multitude of tools and programs out there, all with their own formats and protocols.
 

diff --git a/docs/source/getting_started.md → docs/source/general_architecture.md b/docs/source/getting_started.md → docs/source/general_architecture.md
diff --git a/docs/source/index.md b/docs/source/index.md
@@ -1,34 +1,93 @@
-# Welcome to SimPhoNy docs!
-Here you can browse though the general documentation of SimPhoNy.
+# Welcome to the SimPhoNy docs!
 
-**Compatibility matrix**
+SimPhoNy is an ontology-based open-source Python framework that promotes and enables interoperability between any 3rd-party software tool. Here you can learn more about it.
 
 ```eval_rst
- =============  ==========
- SimPhoNy docs  OSP-core  
- =============  ==========
- 2.3.x          3.4.0-beta
- 2.2.x          3.3.5-beta
- 2.1.x          3.3.0-beta
- =============  ==========
-```
 
-```eval_rst
+.. panels::
+   :body: text-center
+
+   ---
+   **Getting Started**
+
+   Overview, main concepts, and installation guide
+
+   .. link-button:: overview.html
+      :text: To the getting started guides
+      :classes: btn-outline-primary stretched-link
+
+   ---
+   **Usage Guide**
+
+   Core functionalities, wrappers and advanced utilities
+
+   .. link-button:: jupyter/cuds-api.ipynb
+      :text: To the usage guides
+      :classes: btn-outline-primary stretched-link
+
+   ---
+
+   **Working with Ontologies**
+
+   Ontology overview, included ontologies, YAML ontologies and ontology querying
+
+   .. link-button:: ontology_intro.html
+      :text: To the ontology guides 
+      :classes: btn-outline-primary stretched-link
+   ---
+
+   **Wrapper Development**
+
+   A deep dive into the wrapper mechanism for developing new wrappers
+
+   .. link-button:: wrapper_development.html
+      :text: To the wrapper development guides
+      :classes: btn-outline-primary stretched-link
+   ---
+
+   **API Reference**
+
+   Python API of CUDS, the *Session* classes, and other utilities
+
+   .. link-button:: api_ref.html
+      :text: To the API reference
+      :classes: btn-outline-primary stretched-link
+
+   ---
+   **Additional Information**
+
+   License, acknowledgements, data protection, contact info and more
+
+   .. link-button:: contribute.html
+      :text: To get more information
+      :classes: btn-outline-primary stretched-link
+
 .. toctree::
-   :caption: Introduction
+   :hidden:
+   :caption: Getting Started
    :maxdepth: 2
 
-   about.md
-   motivation.md
-   getting_started.md
+   overview.md
+   fundamentals.md
+   general_architecture.md
    installation.md
+
+.. toctree::
+   :hidden:
+   :caption: Usage Guide
+   :maxdepth: 2
+
    jupyter/cuds-api.ipynb
    jupyter/sessions_and_vars.ipynb
    detailed_design.md
    utils.md
+   jupyter/multiple-wrappers.ipynb
+   jupyter/simlammps.ipynb
+   jupyter/quantum-espresso.ipynb
 
 .. toctree::
-   :caption: Ontology
+   :hidden:
+   :caption: Working with Ontologies
    :maxdepth: 2
 
    ontology_intro.md
@@ -37,28 +96,30 @@ Here you can browse though the general documentation of SimPhoNy.
    owl.md
    jupyter/ontology-interface.ipynb
 
-
 .. toctree::
-   :caption: Wrappers
+   :hidden:
+   :caption: Wrapper Development
+   :maxdepth: 2
 
-   jupyter/multiple-wrappers.ipynb
-   jupyter/simlammps.ipynb
-   jupyter/quantum-espresso.ipynb
    wrapper_development.md
    jupyter/wrapper_development.ipynb
 
+.. toctree::
+   :hidden:
+   :caption: API Reference
+   :maxdepth: 2
+
+   api_ref.md
 
 .. toctree::
-   :caption: Additional
+   :hidden:
+   :caption: Additional Info
    :maxdepth: 2
 
    contribute.md
-   api_ref.md
-   json.md
    links.md
    license.md
    Data protection <https://www.simphony-project.eu/en/data_protection.html>
    Imprint <https://www.simphony-project.eu/en/publishing-notes.html>
    contact.md
-
 ```
diff --git a/docs/source/json.md b/docs/source/json.md
diff --git a/docs/source/jupyter/cuds-api.ipynb b/docs/source/jupyter/cuds-api.ipynb
@@ -6,7 +6,9 @@
    "source": [
     "# Tutorial: CUDS API\n",
     "\n",
-    "This tutorial introduces the CUDS API. The code given here is based on [this](https://github.com/simphony/osp-core/blob/master/examples/api_example.py) example."
+    "This tutorial introduces the CUDS API. The code given here is based on [this](https://github.com/simphony/osp-core/blob/master/examples/api_example.py) example.\n",
+    "\n",
+    "Note that that this tutorial, as all others in this documentation, are Jupyter notebooks that can be downloaded by clicking on the \"Edit on Github\" button on the top right of the page."
    ]
   },
   {
@@ -627,4 +629,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 4
-}
+}
diff --git a/docs/source/links.md b/docs/source/links.md
@@ -27,4 +27,23 @@ SimDOME      Horizon 2020  H2020-NMBP-TO-IND-2018-2020  814492
 INTERSECT    Horizon 2020  H2020-NMBP-TO-IND-2018-2020  814487
 ReaxPRO      Horizon 2020  H2020-NMBP-TO-IND-2018-2020  814416
 ===========  ============  ===========================  ===============
-```
+```
+
+
+# Compatibility table
+The following table describes the compatibilities between of SimPhoNy docs and OSP-core.
+
+```eval_rst
+
+.. table::
+   :align: center
+   :widths: auto
+
+   =============  ==========
+   SimPhoNy docs  OSP-core  
+   =============  ==========
+   2.3.x          3.4.0-beta
+   2.2.x          3.3.5-beta
+   2.1.x          3.3.0-beta
+   =============  ==========
+```
diff --git a/docs/source/about.md → docs/source/overview.md b/docs/source/about.md → docs/source/overview.md
@@ -1,19 +1,11 @@
-# About
+# Overview
 
-SimPhoNy is an ontology-based framework that promotes and enables interoperability between any 3rd-party software tool.
-Its [core functionality](https://github.com/simphony/osp-core) is an open-source python project.
-The name ‘SimPhoNy’ stems from the SimPhoNy EU-project in which it was originally developed
-(See more details [here](https://www.simphony-project.eu/)). 
-One of SimPhoNy’s main tasks is to convert *opaque* data, meaning data whose semantics are hidden, to *transparent* data, that is data whose semantics is understood and easily accessible.
-
-This project aims to clarify the purpose and usage of the SimPhoNy platform through simple, short examples.
-In particular, this guide will try to expose the main concepts and components.
-
-All the tutorials in this documentation are Jupyter notebooks that can be downloaded
-by clicking on the "Edit on Github" button on the top right of the page.
+One of SimPhoNy’s main tasks is to convert *opaque* data, whose semantics are hidden from an external user to the system, to *transparent* data, whose semantics are understood and easily accessible by means of a common language, specified by an ontology.
 
 # Terminology
-These are some of the terms used in the following sections:
+The name ‘SimPhoNy’ stems from the SimPhoNy EU-project in which it was originally developed (see more details [here](https://www.simphony-project.eu/)). 
+
+Here are some additional terms that are used throughout the documentation:
 1. `API`: Application Programming Interface. A set of functions that allow the interaction with an application or system.
 1. `OSP`: Open Simulation Platform. 
    A set of common standards and related tools that form the basic environment on top of which compatible and compliant simulation workflows can be developed and run.

diff --git a/docs/source/utils.md b/docs/source/utils.md
@@ -258,3 +258,17 @@ _Examples:_
                                         root=city_cuds,
                                         rel=city.hasInhabitant)
   ```
+## Serialization JSON schema of CUDS objects
+
+When you serialize a CUDS object using the
+[`serialize()` method in the utils module](api_ref.html#osp.core.utils.general.serialize),
+you will get a json document as a result.
+The method will traverse the hierarchical datastructure
+using Depth First Traversal.
+Therefore, its result is a json array composed of several flat CUDS objects.
+
+This array can later be deserialized using the opposite 
+[`deserialize`](api_ref.html#osp.core.utils.general.deserialize).
+
+The serialization is done via [JSON-LD](https://json-ld.org/),
+with the schema used for the [OSP API in Marketplace](https://gitlab.cc-asp.fraunhofer.de/MarketPlace/osp-api).
diff --git a/requirements.txt b/requirements.txt
@@ -9,3 +9,4 @@ ipython
 jupyter
 sphinx-jsonschema
 sphinx-autobuild
+sphinx-panels
diff --git a/setup.py b/setup.py
@@ -18,7 +18,7 @@ def generate_pdf(self):
 setup(
     name=NAME,
     version=VERSION,
-    author='Materials Data Science and Informatics team at Fraunhofer IWM',
+    author='Materials Data Science and Informatics Team at Fraunhofer IWM',
     description='The SimPhoNy documentation',
     keywords='simphony, documentation, sphinx, Fraunhofer IWM',
     long_description=README_TEXT,