Review content to make sure it matches the latest versions (#213)

* Fix references, update requirements Authored-by: Pablo de Andres <pablo.de.andres@iwm.fraunhofer.de>
simphony · Jul 29, 2022 · b50edc5 · b50edc5
1 parent 3f2e5ca
commit b50edc5
Show file tree

Hide file tree

Showing 13 changed files with 506 additions and 392 deletions.
diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css
@@ -16,10 +16,10 @@ h4 {
 }
 
 @media (min-width: 1200px) {
-	.container-xl {
-		max-width: 1550px;
-	}
-	#site-navigation {
-	    max-width: 20%;
-	}
-}
+  .container-xl {
+    max-width: 1550px;
+  }
+  #site-navigation {
+    max-width: 20%;
+  }
+}
diff --git a/docs/source/api_ref.md b/docs/source/api_ref.md
@@ -1,9 +1,4 @@
-```{eval-rst}
-.. raw:: html
-
-    <h1>API Reference</h1>
-
-```
+# API Reference
 
 This document is for developers and/or advanced users of OSP-core, it contains all API details.
 

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -23,9 +23,12 @@
 
 master_doc = "index"
 
+myst_heading_anchors = 5
+
 plantuml = "java -jar lib/plantuml.jar"
 plantuml_output_format = "svg_img"
 
+suppress_warnings = ["autosectionlabel.*"]
 exclude_patterns = ["**.ipynb_checkpoints"]
 
 # HTML output

diff --git a/docs/source/detailed_design.md b/docs/source/detailed_design.md
@@ -2,7 +2,7 @@
 
 Here we will give an in-depth view of the design of the 3 layers.
 
-For a more general overview, go to [getting started](./getting_started.md#general-architecture).
+For a more general overview, go to [general architecture](general_architecture.md).
 
 ```{uml}
   :caption: Standard design
@@ -685,7 +685,7 @@ However, these structures will be used in the different `_apply_<buffer>` method
 Similar to how the `_apply_<buffer>` methods are used to send information to the engine,
 `_load_from_backend` has the purpose of updating the semantic layer with the latest information from the backend.
 
-You can see in the [`get` sequence diagram](#id3) that when the information has potentially
+You can see in the [`get` sequence diagram](#get) that when the information has potentially
 changed in the backend (i.e the simulation has run, or a database has more data)
 the `get` has to fetch the latest version.
 To achieve this, OSP-core calls `_load_from_backend` with the list of desired uids,
@@ -696,7 +696,7 @@ information and `yield` them.
 
 _Location:_ `osp.core.session.transport`
 
-You may have noticed in the [session inheritance scheme](#id2) that there is `TransportSession` implementing the `WrapperSession`.
+You may have noticed in the [session inheritance scheme](#session) that there is `TransportSession` implementing the `WrapperSession`.
 This session class is the way to connect to engines that are located in other machines through web sockets.
 
 The behaviour is as follows:

diff --git a/docs/source/fundamentals.md b/docs/source/fundamentals.md
@@ -164,7 +164,7 @@ and generalising into a middle and top level layers, and it is currently being f
 developed in multiple projects of the European Union.
 
 SimPhoNy is being developed with the intention of being compatible with EMMO, and an easy installation of the
-ontology is available (further explained [here](./ontologies_included.md#working-with-emmo)).
+ontology is available (further explained [here](ontologies_included.md#elementary-multiperspective-material-ontology-emmo)).
 
 There is also [documentation](https://ontology.pages.fraunhofer.de/documentation/latest/) available for developing an EMMO compliant ontology (requires login).
 
@@ -232,14 +232,13 @@ The most used formats for storing RDF data are:
   The example triple in XML is:
 
   ```xml
-    <?xml version="1.0" encoding="utf-8"?>
-    <?xml version="1.0" encoding="utf-8"?>
-    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+  <?xml version="1.0" encoding="UTF-8"?>
+  <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
             xmlns:dbp="http://dbpedia.org/property/">
-        <rdf:Description rdf:about="http://dbpedia.org/resource/The_Lord_of_the_Rings">
-            <dbp:author rdf:resource="http://dbpedia.org/resource/J._R._R._Tolkien"/>
-        </rdf:Description>
-    </rdf:RDF>
+      <rdf:Description rdf:about="http://dbpedia.org/resource/The_Lord_of_the_Rings">
+          <dbp:author rdf:resource="http://dbpedia.org/resource/J._R._R._Tolkien"/>
+      </rdf:Description>
+  </rdf:RDF>
   ```
 
 - [N3](https://www.w3.org/TeamSubmission/n3/): Notation3 is designed with human readability as a motivator.

diff --git a/docs/source/installation.md b/docs/source/installation.md
@@ -1,35 +1,31 @@
 # Installation
 
 For the installation and usage of the framework Python 3.6 or higher is
-needed. OSP-core is available on PyPI, so it can be installed using `pip`:
-
-```shell
-~/test$ pip install osp-core
-```
-
-However, we _highly_ encourage the use of a [virtual environment](https://docs.python.org/3/tutorial/venv.html)
+needed. We _highly_ encourage the use of a [virtual environment](https://docs.python.org/3/tutorial/venv.html)
 or a [conda](https://docs.conda.io/en/latest/) environment.
 
 ```shell
 # virtual environment
-~/test$ python3 -m venv SimPhoNy
-~/test$ source SimPhoNy/bin/activate
-(SimPhoNy) ~/test$
+python3 -m venv SimPhoNy
+source SimPhoNy/bin/activate
 ```
 
 ```shell
 # conda
-~/test$ conda create -n <env name>
-~/test$ conda activate <env name>
+conda create -n <env_name>
+conda activate <env_name>
 ```
 
-Unfortunately, OSP-core is not available on the Anaconda Repository, so
-in both cases, after setting up the environment, it must be installed with
-`pip install osp-core`.
+OSP-core is available on PyPI, so it can be installed using `pip`:
+
+```shell
+pip install osp-core
+```
+
+For an installation from source, see [here](#installing-osp-core-from-source).
 
 After installing OSP-core, you can install your ontology namespaces.
-We provide the tool [`pico`](./utils.md#pico-installs-cuds-ontologies)
-(**p**ico **i**nstalls **c**uds **o**ntologies) for that purpose.
+We provide the [`pico`](utils.md#pico) tool for that purpose.
 
 ```sh
 pico install <path/to/ontology.yml>
@@ -56,7 +52,7 @@ With OSP-core installed, if the wrapper has its own ontology, it _must_ be insta
 pico install <path/to/ontology.yml>
 ```
 
-For the wrappers that require the installation of a backend, a `install_engine.sh` script is provided.
+For the wrappers that require the installation of a backend, a `install_engine.sh` script is usually provided.
 It will automatically call `install_engine_requirements.sh`, where the engine specific requirements are installed.
 
 ```shell
@@ -66,18 +62,14 @@ It will automatically call `install_engine_requirements.sh`, where the engine sp
 Now, the wrapper can be installed:
 
 ```shell
-python3 setup.py install
+pip install .
 ```
 
 ### Wrapper Docker image
 
 Some wrappers also provided a [Dockerfile](https://docs.docker.com/engine/reference/builder/)
 for an automatic installation in a container.
-Simply run the `docker_install.sh` script. There is no need to install OSP-core either.
-
-```shell
-./docker_install.sh
-```
+The dockerfile should contain the information needed to run it inside.
 
 ## Installing OSP-core from source
 

diff --git a/docs/source/jupyter/import_export.ipynb b/docs/source/jupyter/import_export.ipynb
@@ -30,8 +30,8 @@
     "<div class=\"admonition important\">\n",
     "<div class=\"admonition-title\" style=\"font-weight: bold\"><div style=\"display: inline-block\">Tip</div></div>\n",
     "    \n",
-    "The full API specifictions of the import and export functions can be found in the\n",
-    "[utilities API reference page](../api_ref.html#osp.core.utils.export_cuds).\n",
+    "The full API specifications of the import and export functions can be found in the\n",
+    "[utilities API reference page](../api_ref.md#osp.core.utils.export_cuds).\n",
     "    \n",
     "</div>\n",
     "</div>\n"
@@ -42,7 +42,7 @@
    "id": "driving-injury",
    "metadata": {},
    "source": [
-    "For our running example, we'll be using the *city ontology* that was already introduces in the [cuds API tutorial](./cuds_api.html). First, make sure the city ontology is installed. If not, run the following command:"
+    "For our running example, we'll be using the *city ontology* that was already introduces in the [cuds API tutorial](./cuds_api.ipynb). First, make sure the city ontology is installed. If not, run the following command:"
    ]
   },
   {
@@ -284,7 +284,7 @@
     "<div class=\"admonition-title\" style=\"font-weight: bold\"><div style=\"display: inline-block\">Notes</div></div>\n",
     "    \n",
     "1. The format is automatically inferred from the file extension. To specify it explicitly, you can add the `format` parameter, like so: `import_cuds('./data.ttl', format='turtle')`.\n",
-    "1. The `session` parameter is optional and inferred automatically from the context that created by the `with` statement (see the  [tutorial on multiple wrappers](./multiple_wrappers.html) for more information). You can specify the session explicitly like so: `import_cuds('./data.ttl', session=session)`.\n",
+    "1. The `session` parameter is optional and inferred automatically from the context that created by the `with` statement (see the  [tutorial on multiple wrappers](./multiple_wrappers.ipynb) for more information). You can specify the session explicitly like so: `import_cuds('./data.ttl', session=session)`.\n",
     "    \n",
     "</div>"
    ]