diff --git a/docs/source/conf.py b/docs/source/conf.py index d6522b6..3f076ed 100644 --- 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 index 4293900..3003224 100644 --- 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. \ No newline at end of file +from the Materials Data Science and Informatics Team, Fraunhofer IWM. diff --git a/docs/source/motivation.md b/docs/source/fundamentals.md similarity index 98% rename from docs/source/motivation.md rename to docs/source/fundamentals.md index 72e2c72..15fee8f 100644 --- a/docs/source/motivation.md +++ b/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 b/docs/source/general_architecture.md similarity index 100% rename from docs/source/getting_started.md rename to docs/source/general_architecture.md diff --git a/docs/source/index.md b/docs/source/index.md index 392301e..190ca05 100644 --- 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 Imprint contact.md - ``` diff --git a/docs/source/json.md b/docs/source/json.md deleted file mode 100644 index 2f0095e..0000000 --- a/docs/source/json.md +++ /dev/null @@ -1,16 +0,0 @@ - - -# 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/docs/source/jupyter/cuds-api.ipynb b/docs/source/jupyter/cuds-api.ipynb index cec182a..8332172 100644 --- 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 -} +} \ No newline at end of file diff --git a/docs/source/links.md b/docs/source/links.md index b38a1d1..333c48e 100644 --- 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 =========== ============ =========================== =============== -``` \ No newline at end of file +``` + + +# 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 b/docs/source/overview.md similarity index 74% rename from docs/source/about.md rename to docs/source/overview.md index 2ca62e5..2a28cb4 100644 --- a/docs/source/about.md +++ b/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 index 8466c1a..7cb3a00 100644 --- 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 index 728f551..5c1819a 100644 --- 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 index 15b1583..dc5168d 100644 --- 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,