Merge pull request #204 from simphony/dev

Merge release 2.5.0

docs/source/api_ref.md

@@ -84,4 +84,10 @@ This document is for developers and/or advanced users of OSP-core, it contains a
 .. automodule:: osp.core.utils
    :imported-members:
    :members:
-```
+```
+
+### pico
+```{eval-rst}
+.. automodule:: osp.core.pico
+   :members: install, uninstall, packages, namespaces
+```

docs/source/contribute.md

@@ -6,25 +6,31 @@ in order to help those that want to contribute to SimPhoNy.
 ### Tools
 The following are some of the technologies and concepts we use regularly.
 It might be useful to become familiar with them:
- - Version control: Git, GitHub and GitLab
- - Python virtual environments/conda
- - Docker
- - Unittesting
- - Benchmarks
+ - Version control: [Git](https://git-scm.com/),
+   [GitHub](https://github.com/about) and
+   [GitLab](https://about.gitlab.com/)
+ - [Unittest](https://docs.python.org/3/library/unittest.html)
  - Continuous integration
+ - Python virtual environments/[conda](https://docs.conda.io)
+ - [Docker](https://www.docker.com/resources/what-container/)
+ - Benchmarks
 
 ### Code Organisation
 There are 3 main categories of repos:
- - [_OSP-core_](https://github.com/simphony/osp-core) contains the nucleus of SimPhoNy, the base on which the wrappers build.
+ - [_OSP-core_](https://github.com/simphony/osp-core) contains the nucleus of
+   SimPhoNy, the base on which the wrappers build.
  - Each _wrapper_ will be in its own repository on GitHub or GitLab,
-   mimicking [wrapper_development](https://github.com/simphony/wrapper-development).
- - [_docs_](https://github.com/simphony/docs) holds the source for this documentation.
+   mimicking
+   [wrapper_development](https://github.com/simphony/wrapper-development).
+ - [_docs_](https://github.com/simphony/docs)
+   holds the source for this documentation.
 
 There are also 4 types of branches:
  - `master/main` contains all the releases, and should always be stable.
  - `dev` holds the code for the newest release that is being developed.
  - `issue branch` is where an specific issue is being solved.
- - `hotfix branch` is where a critical software bug detected on the stable release (more on this later) is being solved.
+ - `hotfix branch` is where a critical software bug detected on the stable
+   release (more on this later) is being solved.
 
 All wrappers and OSP-core are part of a common directory structure:
 - _`osp/`_: contains all the SimPhoNy source code.
@@ -38,10 +44,12 @@ All wrappers and OSP-core are part of a common directory structure:
 - Every new feature or bug is defined in an issue and labelled accordingly.  
  If there is something that is missing or needs improving,
  make an issue in the appropriate project.
-- Generally, the issues are fixed by creating a new `issue branch` from the `dev` branch, committing to that branch and making a new Pull/Merge Request when done. 
-  An owner of the project should be tagged for review.
-  They will review and merge the PR if the fix is correct, deleting the `issue branch` afterwards.
-  The changes should be clearly explained in the issue/Pull Request.
+- Generally, the issues are fixed by creating a new `issue branch` from the
+  `dev` branch, committing to that branch and making a new Pull/Merge 
+  Request when done. An owner of the project should be tagged for review.
+  They will review and merge the PR if the fix is correct, deleting the
+  `issue branch` afterwards. The changes should be clearly explained in the 
+  issue/Pull Request.
 ```{warning}
    If the issue is a critical software bug detected in the stable release, a 
    `hotfix branch` should be created from the `master/main` branch 
@@ -54,15 +62,17 @@ All wrappers and OSP-core are part of a common directory structure:
    `hotfix branch`.
 ```
 - Once the features for a release have been reached, `dev` will be merged to 
-  `master/main`. Every new commit in the `master/main` branch generally corresponds 
-  to a new release, which is labelled with a 
+  `master/main`. Every new commit in the `master/main` branch generally 
+  corresponds to a new release, which is labelled with a 
   [git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) matching its 
-  version number. An exception to this rule may apply, for example when several 
-  critical hotfixes are applied in a row, as it would then be better to just to 
-  publish a single release afterwards. In regard to version numbering, we adhere to the 
+  version number. An exception to this rule may apply, for example when 
+  several critical hotfixes are applied in a row, as it would then be 
+  better to just to publish a single release afterwards. In regard to 
+  version numbering, we adhere to the 
   [_Semantic versioning_](https://semver.org/) rules.
 
-In the next image it can be seen how the branches usually look during this workflow, and the different commits used to synchronise them:
+In the next image it can be seen how the branches usually look during this 
+workflow, and the different commits used to synchronise them:
 
 <figure style="display: table; text-align:center; margin-left: auto; margin-right:auto">
 
@@ -73,32 +83,71 @@ In the next image it can be seen how the branches usually look during this workf
 ## Coding
 ### Documenting
 - All code must be  properly documented with meaningful comments.
-- For readability, we now follow the [Google docstring format](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings).
+- For readability, we now follow the 
+  [Google docstring format](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings).
 - If some behaviour is very complex, in-line comments can be used. 
   However, proper naming and clear operations are always preferred.
 
+### Code style
+- Code should follow
+  [PEP8 code style conventions](https://peps.python.org/pep-0008/).
+- All Python code should be validated by the 
+  [Flake8](https://github.com/pycqa/flake8) tool. The validation is also 
+  enforced on the repository by the
+  [continuous integration](contribute.md#continuous-integration). Click 
+  [here](https://github.com/simphony/osp-core/blob/master/.github/workflows/ci.yml#L12)
+  to see the specific options with which Flake8 is launched.
+- All Python code should be reformatted with
+  [black](https://github.com/psf/black) and 
+  [isort](https://github.com/PyCQA/isort). The use of said tools is 
+  enforced by the
+  [continuous integration](contribute.md#continuous-integration). Therefore,
+  we strongly recommend that you use the
+  [configuration file](https://github.com/simphony/osp-core/blob/master/.pre-commit-config.yaml)
+  bundled with the repository to
+  [install](https://pre-commit.com/#installation) the
+  [pre-commit framework](https://pre-commit.com/), that automates the task 
+  using git pre-commit hooks.
+- A few
+  [other style conventions](https://github.com/simphony/osp-core/blob/master/.pre-commit-config.yaml)
+  are also enforced by the continuous integration through
+  [pre-commit](https://pre-commit.com/) (such as empty lines at the end of 
+  text files). If you decide not to use it, the CI will let you know what 
+  to correct.
+
 ### Testing
-- All Python code should pass Flake8 tests.
 - All complex functionality must be tested.
-- If some implementation can not be checked through unittest, it should be at least manually run in different systems to assure an expected behaviour.
+- If some implementation can not be checked through unittest, it should be 
+  at least manually run in different systems to assure an expected behaviour.
 
 ### Continuous Integration
 - We currently run the CI through Github Actions/GitLab CI.
-- Flake8 and unittests are automatically run for all PR. 
-- For the OSP-core code, benchmarks are run after every merge to `dev`. Benchmark results are 
-  available [here](https://simphony.github.io/osp-core/dev/bench/index.html). 
-  The CI will report a failure when a benchmark is 50% slower than in the previous run, in addition to automatically commenting on the commit. 
+- Code style conventions are enforced through the use of Flake8, black, isort, 
+  and various 
+  [pre-commit](https://pre-commit.com/) 
+  [hooks](https://github.com/simphony/osp-core/blob/master/.pre-commit-config.yaml).
+- Tests are automatically run for all pull requests. 
+- For the OSP-core code, benchmarks are run after every merge to `dev`. 
+  Benchmark results are available
+  [here](https://simphony.github.io/osp-core/dev/bench/index.html). The CI 
+  will report a failure when a benchmark is 50% slower than in the previous 
+  run, in addition to automatically commenting on the commit. 
 
 ### Naming conventions
-- Use `cuds_object` as the argument name of your methods (not `entity`, `cuds`, `cuds_instance`...).
-- The official spelling is `OSP-core` (as opposed to _osp core_, _OSP-Core_ or similar).
+- Use `cuds_object` as the argument name of your methods (not `entity`, 
+  `cuds`, `cuds_instance`...).
+- The official spelling is `OSP-core` (as opposed to _osp core_, _OSP-Core_ 
+  or similar).
 
 ## Contribute to OSP-core
-If you are not a member of the [SimPhoNy organisation](https://github.com/simphony), rather than creating a branch
-from `dev`, you will have to fork the repository and create the Pull Request.
+If you are not a member of the
+[SimPhoNy organisation](https://github.com/simphony), rather than creating 
+a branch from `dev`, you will have to fork the repository and create the 
+Pull Request.
 
 ## Contribute to wrapper development
-For a sample wrapper, visit the [wrapper_development](https://github.com/simphony/wrapper-development) repo.
+For a sample wrapper, visit the
+[wrapper_development](https://github.com/simphony/wrapper-development) repo.
 
 README files should include:
 - Information regarding the purpose of the wrapper and the backend used.
@@ -108,6 +157,7 @@ README files should include:
 - Any other necessary information for users and other developers.
 
 ## Contribute to the docs
-If you have any suggestion for this documentation, whether it is something that needs more explanation, is inaccurate or simply a note on anything that could be improved, you can open an issue [here](https://github.com/simphony/docs/issues), and we will look into it!.
-
-
+If you have any suggestion for this documentation, whether it is something 
+that needs more explanation, is inaccurate or simply a note on anything 
+that could be improved, you can open an issue
+[here](https://github.com/simphony/docs/issues), and we will look into it!.

docs/source/general_architecture.md

@@ -133,8 +133,8 @@ It is independent of any backend and provides the basic ontology based data stru
 ### Ontology file
 OSP-core requires an ontology file to create the appropriate CUDS classes.
 
-Said ontology must be either in a YAML format as defined by [our specification](yaml.md)
-or [one of the supported owl ontologies](owl.md).
+Said ontology must be either in a YAML format as defined by [our specification](working_with_ontologies.md#osp-core-yaml-ontology-format)
+or [one of the supported owl ontologies](working_with_ontologies.md#owl-ontologies-and-rdfs-vocabularies).
 
 <details>
   <summary>YAML Ontology sample</summary>

docs/source/index.md

@@ -77,9 +77,9 @@ installation
 :caption: Usage Guide
 :maxdepth: 2
 
+utils
 jupyter/cuds_api
 jupyter/sessions_and_vars
-utils
 jupyter/multiple_wrappers
 jupyter/import_export
 jupyter/simlammps
@@ -92,9 +92,8 @@ jupyter/quantum_espresso
 :maxdepth: 2
 
 ontology_intro
+working_with_ontologies
 ontologies_included
-yaml
-owl
 jupyter/ontology_interface
 ```
 

docs/source/jupyter/cuds_api.ipynb

@@ -63,7 +63,7 @@
     "\n",
     "- `attributes`: The values of the ontology attributes of an individual (also known as [data properties](https://www.w3.org/TR/owl2-syntax/#Data_Properties) in [OWL](https://en.wikipedia.org/wiki/Web_Ontology_Language)) may also be accessed and modified as python properties of the CUDS objects. For example: `cuds_object.name = \"Bob\"`.\n",
     "\n",
-    "There are some advanced functionalities NOT covered in this tutorial. Among them, we highlight the `update` method, which is covered in the [wrapper tutorial](multiple-wrappers.ipynb), where it can be seen in action. For a complete list of available methods and properties, check the API reference. That whole set of methods and attributes constitutes the CUDS [API](https://en.wikipedia.org/wiki/API).\n",
+    "There are some advanced functionalities NOT covered in this tutorial. Among them, we highlight the `update` method, which is covered in the [wrapper tutorial](multiple_wrappers.ipynb), where it can be seen in action. For a complete list of available methods and properties, check the API reference. That whole set of methods and attributes constitutes the CUDS [API](https://en.wikipedia.org/wiki/API).\n",
     "\n",
     "[//]: # (TODO: Link to API reference.)"
    ]
@@ -88,7 +88,7 @@
     }
    },
    "source": [
-    "The first step is to install the city ontology. Use the tool pico for this. If you want to know more about ontology installation, check the documentation on the [pico ontology installation tool](https://simphony.readthedocs.io/en/latest/utils.html#pico-installs-cuds-ontologies), [YAML ontology installation files](https://simphony.readthedocs.io/en/latest/yaml.html), and [installing OWL ontologies](https://simphony.readthedocs.io/en/latest/owl.html)."
+    "The first step is to install the city ontology. Use the tool pico for this. If you want to know more about ontology installation, check the documentation on the [pico ontology installation tool](https://simphony.readthedocs.io/en/latest/utils.html#pico-installs-cuds-ontologies), [YAML ontology installation files](https://simphony.readthedocs.io/en/latest/working_with_ontologies.html#osp-core-yaml-ontology-format), and [installing OWL ontologies](https://simphony.readthedocs.io/en/latest/working_with_ontologies.html#owl-ontologies-and-rdfs-vocabularies)."
    ]
   },
   {

docs/source/jupyter/ontology_interface.ipynb

@@ -28,7 +28,7 @@
    "source": [
     "In an ontological framework, ontology entities are used as a knowledge representation form. Those can be further categorized in two groups: ontology individuals ([assertional knowledge](https://en.wikipedia.org/wiki/Abox)), and ontology classes, relationships and attributes ([terminological knowledge](https://en.wikipedia.org/wiki/Tbox)).\n",
     "\n",
-    "In a [previous tutorial](./cuds_api.html), we have discussed how to work with CUDS objects, which represent ontology individuals. In this tutorial, we present the API of all the other entities instead: ontology classes, relationships and attributes. These are defined in an ontology installation file in [YAML](../yaml.md) or [OWL](../owl.md) format. The presented API enables you to access the entities and navigate within an ontology."
+    "In a [previous tutorial](./cuds_api.html), we have discussed how to work with CUDS objects, which represent ontology individuals. In this tutorial, we present the API of all the other entities instead: ontology classes, relationships and attributes. These are defined in an ontology installation file in [YAML](../working_with_ontologies.md#osp-core-yaml-ontology-format) or [OWL](../working_with_ontologies.md#owl-ontologies-and-rdfs-vocabularies) format. The presented API enables you to access the entities and navigate within an ontology."
    ],
    "metadata": {}
   },
@@ -195,7 +195,7 @@
    "source": [
     "The **most convenient way** to access an ontology entity is using the **dot notation** in python. For example, `city.Citizen`. This method is a shorthand for fetching by suffix or label:  \n",
     "\n",
-    "- When the keyword `reference_by_label` is set to `True` (enabled) in the [ontology YAML installation file](../owl.md), the dot notation is a shorthand for fetching by label. This keyword is **enabled** in the `math` namespace.\n",
+    "- When the keyword `reference_by_label` is set to `True` (enabled) in the [ontology YAML installation file](../working_with_ontologies.md), the dot notation is a shorthand for fetching by label. This keyword is **enabled** in the `math` namespace.\n",
     "\n",
     "- When the keyword `reference_by_label` is set to `False` (disabled) or not set, the dot notation is a shorthand for fetching by suffix instead. This keyword is **disabled** in the `city` namespace."
    ],