Update API reference (#226)

* Merge the API reference page into the additional information section.

* Update the API reference panel on the main page.

* Add missing functions and classes to API reference. Select methods that are meant to be in the public API, hide methods that are not.

* Trick Sphinx Automodule into thinking that some module members have different names and live in different modules.

* Update requirements.txt.

Author: kysrpex

docs/api_reference.md

@@ -1,95 +1,165 @@
 # API Reference
 
-This document is for developers and/or advanced users of OSP-core, it contains all API details.
+This document is for advanced users of SimPhoNy and defines all its public API
+details. This means that only when there is a breaking change in any of the
+methods listed on this page, the major version number of SimPhoNy
+will change accordingly, as prescribed by the
+[Semantic Versioning Specification](https://semver.org/spec/v2.0.0.html#spec-item-8).
 
-## CUDS
+**Do not rely** on the stability of methods not listed on this page.
+
+If the `__init__` method is not listed for a class, you are **not expected
+to instantiate such class by yourself**, and thus doing so is unsupported.
+
+## Ontology management
 
 ```{eval-rst}
-.. autoclass:: osp.core.cuds.Cuds
-    :members:
-    :show-inheritance:
+.. autofunction:: simphony_osp.tools.pico.install
+
+.. autofunction:: simphony_osp.tools.pico.uninstall
+
+.. autofunction:: simphony_osp.tools.pico.packages
+
+.. autofunction:: simphony_osp.tools.pico.namespaces
 ```
 
-## Ontology interface
+## Terminological- and assertional knowledge
 
 ```{eval-rst}
-.. autoclass:: osp.core.ontology.namespace.OntologyNamespace
-    :members:
-    :special-members: __getattr__, __getitem__, __contains__, __iter__, __eq__
+.. autoclass:: simphony_osp.ontology.OntologyNamespace
+    :members: from_iri, from_label, from_suffix, get, iri, name
+    :special-members: __getattr__, __getitem__, __contains__, __iter__, __eq__,
+        __len__
     :show-inheritance:
 
-.. autoclass:: osp.core.ontology.entity.OntologyEntity
-    :members:
+.. autoclass:: simphony_osp.ontology.OntologyEntity
+    :members: direct_subclasses, direct_superclasses, identifier, iri, is_subclass_of, is_superclass_of, iter_labels, label, label_lang, label_literal, namespace, session, subclasses, superclasses, triples
+    :special-members: __bool__, __eq__
+
+.. autoclass:: simphony_osp.ontology.OntologyClass
+    :members: attributes, optional_attributes, axioms
+    :special-members: __call__
     :show-inheritance:
 
-.. autoclass:: osp.core.ontology.oclass.OntologyClass
-    :members:
+.. autoclass:: simphony_osp.ontology.Restriction
+    :members: quantifier, target, relationship, attribute, rtype
     :show-inheritance:
 
-.. autoclass:: osp.core.ontology.oclass_restriction.Restriction
+.. autoclass:: simphony_osp.ontology.RESTRICTION_QUANTIFIER
     :members:
+    :undoc-members:
     :show-inheritance:
 
-.. autoclass:: osp.core.ontology.oclass_composition.Composition
+.. autoclass:: simphony_osp.ontology.RESTRICTION_TYPE
     :members:
+    :undoc-members:
     :show-inheritance:
 
-.. autoclass:: osp.core.ontology.relationship.OntologyRelationship
-    :members:
+.. autoclass:: simphony_osp.ontology.Composition
+    :members: operator, operands
     :show-inheritance:
 
-.. autoclass:: osp.core.ontology.attribute.OntologyAttribute
+.. autoclass:: simphony_osp.ontology.COMPOSITION_OPERATOR
     :members:
+    :undoc-members:
     :show-inheritance:
-```
-
-## Sessions
 
-```{eval-rst}
-.. autoclass:: osp.core.session.session.Session
-    :members:
+.. autoclass:: simphony_osp.ontology.OntologyRelationship
+    :members: inverse
     :show-inheritance:
 
-.. autoclass:: osp.core.session.core_session.CoreSession
-    :members:
+.. autoclass:: simphony_osp.ontology.OntologyAttribute
+    :members: datatype
     :show-inheritance:
 
-.. autoclass:: osp.core.session.wrapper_session.WrapperSession
-    :members:
+.. autoclass:: simphony_osp.ontology.OntologyAnnotation
     :show-inheritance:
 
-.. autoclass:: osp.core.session.sim_wrapper_session.SimWrapperSession
-    :members:
+.. autoclass:: simphony_osp.ontology.OntologyIndividual
+    :members: classes, is_a, connect, disconnect, get, iter, operations, attributes
+    :special-members: __getattr__, __setattr__, __getitem__, __setitem__, __delitem__
     :show-inheritance:
 
-.. autoclass:: osp.core.session.db.db_wrapper_session.DbWrapperSession
-    :members:
+.. autoclass:: simphony_osp.ontology.RelationshipSet
+    :members: update, intersection_update, difference_update, symmetric_difference_update, inverse
+    :inherited-members: individual, predicate, one, any, all, isdisjoint, clear, pop, copy, difference, discard, intersection, issubset, issuperset, add, remove, symmetric_difference, union
+    :special-members: __iter__, __contains__, __invert__, __len__, __le__, __lt__, __ne__, __gt__, __ge__, __and__, __radd__, __ror__, __rsub__, __rxor__, __or__, __xor__, __iadd__, __isub__, __ior__, __iand__, __ixor__
+    :exclude-members: iter_low_level, prevent_class_filtering
+
+.. autoclass:: simphony_osp.ontology.AttributeSet
+    :members: update, intersection_update, difference_update, symmetric_difference_update
+    :inherited-members: individual, predicate, one, any, all, isdisjoint, clear, pop, copy, difference, discard, intersection, issubset, issuperset, add, remove, symmetric_difference, union
+    :special-members: __iter__, __contains__, __len__, __le__, __lt__, __ne__, __gt__, __ge__, __and__, __radd__, __ror__, __rsub__, __rxor__, __or__, __xor__, __iadd__, __isub__, __ior__, __iand__, __ixor__
+
+.. autoclass:: simphony_osp.ontology.AnnotationSet
+    :members: update, intersection_update, difference_update, symmetric_difference_update
+    :inherited-members: individual, predicate, one, any, all, isdisjoint, clear, pop, copy, difference, discard, intersection, issubset, issuperset, add, remove, symmetric_difference, union
+    :special-members: __iter__, __contains__, __len__, __le__, __lt__, __ne__, __gt__, __ge__, __and__, __radd__, __ror__, __rsub__, __rxor__, __or__, __xor__, __iadd__, __isub__, __ior__, __iand__, __ixor__
+
+.. autoclass:: simphony_osp.ontology.ResultEmptyError
     :show-inheritance:
 
-.. autoclass:: osp.core.session.db.sql_wrapper_session.SqlWrapperSession
-    :members:
+.. autoclass:: simphony_osp.ontology.MultipleResultsError
     :show-inheritance:
 ```
 
-## Registry
+## Sessions and wrappers
 
 ```{eval-rst}
-.. autoclass:: osp.core.session.registry.Registry
-    :members:
+.. autoclass:: simphony_osp.session.Session
+    :members: commit, compute, close, sparql, identifier, update, from_label, add, delete, clear, get, iter
+    :inherited-members: locked
+    :special-members: __init__, __iter__,  __contains__, __enter__, __exit__, __len__,
+    :exclude-members: bind, default-ontology, driver, entity_cache_timestamp, from_identifier, from_identifier_typed, get_default_environment, get_default_session, get_entities, get_identifiers, get_namespace, get_namespace_bind, graph, iter_labels, label_languages, label_predicates, load_parser, lock, unlock, merge, namespaces, ontology, set_default_session, subscribers, unbind, unlock, update, iter_identifiers, default_ontology
+
+.. autoclass:: simphony_osp.session.SessionSet
+    :members: update, intersection_update, difference_update, symmetric_difference_update
+    :inherited-members: individual, predicate, one, any, all, isdisjoint, clear, pop, copy, difference, discard, intersection, issubset, issuperset, add, remove, symmetric_difference, union
+    :special-members: __iter__, __contains__, __len__, __le__, __lt__, __ne__, __gt__, __ge__, __and__, __radd__, __ror__, __rsub__, __rxor__, __or__, __xor__, __iadd__, __isub__, __ior__, __iand__, __ixor__
+
+.. autoclass:: simphony_osp.session.core_session
     :show-inheritance:
+
+.. autofunction:: simphony_osp.tools.import_file
+
+.. autofunction:: simphony_osp.tools.export_file
 ```
 
-## Utilities
+### Search
 
 ```{eval-rst}
-.. automodule:: osp.core.utils
-   :imported-members:
-   :members:
+.. autofunction:: simphony_osp.tools.search.find
+
+.. autofunction:: simphony_osp.tools.search.find_by_identifier
+
+.. autofunction:: simphony_osp.tools.search.find_by_class
+
+.. autofunction:: simphony_osp.tools.search.find_by_attribute
+
+.. autofunction:: simphony_osp.tools.search.find_relationships
+
+.. autofunction:: simphony_osp.tools.search.sparql
 ```
 
-### pico
+## Visualization
 
 ```{eval-rst}
-.. automodule:: osp.core.pico
-   :members: install, uninstall, packages, namespaces
+
+.. autofunction:: simphony_osp.tools::semantic2dot
+
+.. autoclass:: simphony_osp.tools.semantic2dot::Semantic2Dot
+    :members: render, _repr_mimebundle_
+
+.. autofunction:: simphony_osp.tools.pretty_print
+```
+
+## Tools
+
+```{eval-rst}
+
+.. autofunction:: simphony_osp.tools.host
+
+.. autofunction:: simphony_osp.tools.branch
+
+.. autofunction:: simphony_osp.tools.relationships_between
 ```

docs/conf.py

@@ -65,3 +65,21 @@
 latex_elements = {"figure_align": "H"}
 
 nbsphinx_allow_errors = True
+
+
+def setup(app):
+    import simphony_osp.ontology
+
+    # Override names and modules of members of "simphony_osp.ontology" in the
+    # API reference.
+    for obj in simphony_osp.ontology.__all__:
+        item = getattr(simphony_osp.ontology, obj)
+        setattr(item, "__name__", obj)
+        setattr(item, "__module__", simphony_osp.ontology.__name__)
+
+    # Override names and modules of members of "simphony_osp.session" in the
+    # API reference.
+    for obj in simphony_osp.session.__all__:
+        item = getattr(simphony_osp.session, obj)
+        setattr(item, "__name__", obj)
+        setattr(item, "__module__", simphony_osp.session.__name__)

docs/index.md

@@ -54,7 +54,7 @@ SimPhoNy enables:
 
    Python API of CUDS, the *Session* classes, and other utilities
 
-   ```{link-button} api_ref.html
+   ```{link-button} api_reference.html
       :text: To the API reference
       :classes: btn-outline-primary stretched-link
 
@@ -113,17 +113,10 @@ usage/visualization
 
 ```{toctree}
 :hidden: true
-:caption: API Reference
+:caption: Additional Info
 :maxdepth: 2
 
 api_reference
-```
-
-```{toctree}
-:hidden: true
-:caption: Additional Information
-:maxdepth: 2
-
 contribute
 links
 license

requirements.txt

@@ -1,4 +1,4 @@
-git+https://github.com/simphony/osp-core.git#egg=osp-core
+simphony-osp == 4.0.0rc3
 jinja2 >= 3.0.3, < 4
 jupyter >= 1.0.0, < 2
 markupsafe >= 2.1.1, < 3