upgrade sphinx. Fixes #512 (#513)

* upgrade sphinx. Fixes #512 * doc-refactor * refactor * Update obo_graph_to_fhir_converter.py --------- Co-authored-by: Harshad <[email protected]>
INCATools · Apr 4, 2023 · 32556dc · 32556dc
1 parent 23cf599
commit 32556dc
Show file tree

Hide file tree

Showing 68 changed files with 263 additions and 606 deletions.
diff --git a/docs/best-practice.rst b/docs/best-practice.rst
diff --git a/docs/concepts.rst b/docs/concepts.rst
@@ -1,5 +1,7 @@
 .. _concepts:
 
+**NOTE** this is largely replaced by the :ref:`guide`
+
 Ontology Concepts
 =================
 

diff --git a/docs/contributing.md b/docs/contributing.md
@@ -2,8 +2,6 @@
 
 All contributions are welcome!
 
-But we warned until [v0.2.0](https://github.com/INCATools/ontology-access-kit/milestone/1) things may be in flux!
-
 ## Reporting issues and giving general feedback
 
 Please use the [issue tracker](https://github.com/INCATools/ontology-access-kit/issues) for questions, bugs, enhancements, feature requests, etc

diff --git a/docs/index.rst b/docs/index.rst
@@ -10,17 +10,11 @@ Ontology Access Kit (OAK) Documentation
    introduction
    intro/index
    guide/index
-   architecture
-   interfaces/index
-   implementations/index
+   packages/index
    cli
-   selectors
    datamodels/index
-   converters/index
-   utilities
    howtos/index
    notebooks
-   concepts
    glossary
    faq
 

diff --git a/docs/introduction.md b/docs/introduction.md
diff --git a/docs/introduction.rst b/docs/introduction.rst
@@ -0,0 +1,52 @@
+Introduction
+------------
+
+Ontology Access Toolkit (OAK) is a Python library for common
+:term:`Ontology` operations over a variety of :term:`Adapters<Adapter>`.
+
+This library provides a collection of different :term:`Interfaces<Interface>` for different
+kinds of ontology operations, including:
+
+-  basic features of an :term:`Ontology Element`, such as its :term:`Label`, :term:`Definition`,
+   :term:`Relationships<Relationship>`, or :term:`Synonyms<Synonym>`.
+-  :term:`Search` an ontology for a term.
+-  :term:`Apply` modifications to terms, including adding, deleting, or updating
+-  numerous specialized operations, such as :term:`Graph Traversal`, or :term:`Axiom` processing,
+   :term:`Ontology Alignment`, or :term`Text Annotation`.
+
+These interfaces are *separated* from any particular backend. This means
+the same API can be used regardless of whether the ontology:
+
+-  is served by a remote API such as :term:`OLS` or :term:`BioPortal`.
+-  is present locally on the filesystem in :term:`OWL`, :term:`OBO Format`,
+   :term:`OBO Graphs`, or :term:`SQLite` formats.
+-  is to be downloaded from a remote :term:`Ontology Repository` such as the :term:`OBO Library`.
+-  is queried from a remote database, including :term:`SPARQL` endpoints, A SQL
+   database, a Solr/ES endpoint.
+
+Basic Python Example
+~~~~~~~~~~~~~~~~~~~~
+
+The following code will load an ontology from a :term:`SQLite` database, lookup
+basic information on terms matching a search
+
+.. code:: python
+
+   >>> from oaklib import get_adapter
+   >>> adapter = get_adapter("sqlite:obo:cl")
+   >>> for curie in adapter.basic_search("T cell"):
+   ...     print(f'{curie} ! {si.label(curie)}')
+   ...     print(f'Definition: {si.definition(curie)}')
+   ...     for rel, fillers in si.outgoing_relationship_map(curie).items():
+   ...         print(f'  RELATION: {rel} ! {si.label(rel)}')
+   ...         for filler in fillers:
+   ...             print(f'     * {filler} ! {si.label(filler)}')
+
+Basic Command Line Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: bash
+
+   $ runoak -i sqlite:obo:obi info "assay"
+
+This does a basic lookup of the term "assay" in :term:`OBI`
diff --git a/docs/architecture.rst → docs/packages/architecture.rst b/docs/architecture.rst → docs/packages/architecture.rst
@@ -16,7 +16,7 @@ you can do on an ontology, mostly simple lookup operations. Here is a simplified
 
 .. mermaid::
 
-  classDiagram
+   classDiagram
       class OntologyInterface {
           +interfaces_implemented()
       }

diff --git a/docs/packages/best-practice.rst b/docs/packages/best-practice.rst
@@ -0,0 +1,83 @@
+.. _best_practice:
+
+Best Practice
+=============
+
+External Services
+-----------------
+
+Consider making your code robust regardless of whether the ontology implementation is local or a remote service.
+
+Iterators
+^^^^^^^^^
+
+Most interface methods that provide more that one result will return :term:`Iterator`s which yield individual elements.
+You can iterate over these in exactly the same way you iterate over lists, for example:
+
+.. code:: python
+
+    >>> for curie in oi.basic_search("cell"):
+    >>>     ## do something with results
+    >>>     print(f'MATCH: {curie}')
+
+If you like you can directly convert an iterator to a list:
+
+.. code:: python
+
+    >>> curies = list(oi.basic_search("cell"))
+
+However, this may be an anti-pattern if the implementation is a remote service and the results include possible thousands of results,
+as this will block on waiting for all results.
+
+For more on iterators, see `How to Use Generators and yield in Python <https://realpython.com/introduction-to-python-generators/>`_
+
+Weaving calls together
+^^^^^^^^^^^^^^^^^^^^^^
+
+A common pattern is to iterate over a result set and issue a separate call for each result:
+
+.. code:: python
+
+    >>> for curie in oi.basic_search("cell"):
+            >>>     print(f'MATCH: {curie} ! {oi.label(curie)}')
+
+        This is fine if the implementation has a low latency for individual calls, but if the implementation is backed by
+        a remote service (for example, a SPARQL endpoint like ontobee or ubergraph, or a remote SQL database) then this will
+        issue one network call for each result, which may be inefficient.
+
+        One possibility is to use a dedicated method for retrieving batch results, for example
+        >>>     print(f'MATCH: {curie} ! {oi.get_label_by_curie(curie)}')
+
+A better approach is to *chunk* over iterators:
+
+Chunking
+^^^^^^^^
+
+The :ref:`.chunk` utility function will chunk iterator calls into sizeable amounts:
+
+.. code:: python
+
+    >>> for curie_it in chunk(impl.basic_search(t)):
+        >>>     logging.info('** Next chunk:')
+        >>>     for curie, label in impl.labels(curie_it):
+        >>>         print(f'{curie} ! {label}')
+
+    This is slightly more boilerplate code, and may not be necessary for an in-memory implementation like Pronto. However, this
+    pattern could have considerable advantages for result sets that are potentially large. Even if the external server is
+    slow to return results, users will see batches or results rather than waiting on the external server to produce
+    >>>     logging.info('** Next chunk:')
+    >>>     for curie, label in impl.get_labels_for_curies(curie_it):
+    >>>         print(f'{curie} ! {label}')
+
+This is slightly more boilerplate code, and may not be necessary for an in-memory implementation like Pronto. However, this
+pattern could have considerable advantages for result sets that are potentially large. Even if the external server is
+slow to return results, users will see batches or results rather than waiting on the external server to produce *all* results.
+
+Command Line
+------------
+
+If you are extending the CLI module or writing a Python application that uses OAK:
+
+- Use click
+- Follow CLIG guidelines
+- Ensure that there are tests for the command line using test_click
diff --git a/docs/converters/data-model-converter.rst → ...kages/converters/data-model-converter.rst b/docs/converters/data-model-converter.rst → ...kages/converters/data-model-converter.rst
diff --git a/docs/converters/index.rst → docs/packages/converters/index.rst b/docs/converters/index.rst → docs/packages/converters/index.rst
diff --git a/docs/converters/obo-graph-to-cx.rst → docs/packages/converters/obo-graph-to-cx.rst b/docs/converters/obo-graph-to-cx.rst → docs/packages/converters/obo-graph-to-cx.rst
diff --git a/docs/converters/obo-graph-to-fhir.rst → ...packages/converters/obo-graph-to-fhir.rst b/docs/converters/obo-graph-to-fhir.rst → ...packages/converters/obo-graph-to-fhir.rst
diff --git a/docs/converters/obo-graph-to-obo-format.rst → ...es/converters/obo-graph-to-obo-format.rst b/docs/converters/obo-graph-to-obo-format.rst → ...es/converters/obo-graph-to-obo-format.rst
diff --git a/docs/converters/obo-graph-to-owl.rst → .../packages/converters/obo-graph-to-owl.rst b/docs/converters/obo-graph-to-owl.rst → .../packages/converters/obo-graph-to-owl.rst
diff --git a/docs/implementations/aggregator.rst → docs/packages/implementations/aggregator.rst b/docs/implementations/aggregator.rst → docs/packages/implementations/aggregator.rst
diff --git a/docs/implementations/bioportal.rst → docs/packages/implementations/bioportal.rst b/docs/implementations/bioportal.rst → docs/packages/implementations/bioportal.rst
diff --git a/docs/implementations/gilda.rst → docs/packages/implementations/gilda.rst b/docs/implementations/gilda.rst → docs/packages/implementations/gilda.rst
diff --git a/docs/implementations/index.rst → docs/packages/implementations/index.rst b/docs/implementations/index.rst → docs/packages/implementations/index.rst
diff --git a/docs/implementations/obograph.rst → docs/packages/implementations/obograph.rst b/docs/implementations/obograph.rst → docs/packages/implementations/obograph.rst
diff --git a/docs/implementations/ols.rst → docs/packages/implementations/ols.rst b/docs/implementations/ols.rst → docs/packages/implementations/ols.rst
diff --git a/docs/implementations/ontobee.rst → docs/packages/implementations/ontobee.rst b/docs/implementations/ontobee.rst → docs/packages/implementations/ontobee.rst
diff --git a/docs/implementations/owlery.rst → docs/packages/implementations/owlery.rst b/docs/implementations/owlery.rst → docs/packages/implementations/owlery.rst
diff --git a/docs/implementations/pronto.rst → docs/packages/implementations/pronto.rst b/docs/implementations/pronto.rst → docs/packages/implementations/pronto.rst
diff --git a/docs/implementations/simple_obo.rst → docs/packages/implementations/simple_obo.rst b/docs/implementations/simple_obo.rst → docs/packages/implementations/simple_obo.rst
diff --git a/docs/implementations/sparql.rst → docs/packages/implementations/sparql.rst b/docs/implementations/sparql.rst → docs/packages/implementations/sparql.rst
diff --git a/docs/implementations/sqldb.rst → docs/packages/implementations/sqldb.rst b/docs/implementations/sqldb.rst → docs/packages/implementations/sqldb.rst
diff --git a/docs/implementations/ubergraph.rst → docs/packages/implementations/ubergraph.rst b/docs/implementations/ubergraph.rst → docs/packages/implementations/ubergraph.rst
diff --git a/docs/packages/index.rst b/docs/packages/index.rst
@@ -0,0 +1,15 @@
+.. _packages:
+
+Package Documentation
+==================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   architecture
+   interfaces/index
+   implementations/index
+   selectors
+   converters/index
+   utilities
diff --git a/docs/interfaces/association-provider.rst → ...kages/interfaces/association-provider.rst b/docs/interfaces/association-provider.rst → ...kages/interfaces/association-provider.rst
diff --git a/docs/interfaces/basic.rst → docs/packages/interfaces/basic.rst b/docs/interfaces/basic.rst → docs/packages/interfaces/basic.rst
diff --git a/docs/interfaces/class-enrichment.rst → .../packages/interfaces/class-enrichment.rst b/docs/interfaces/class-enrichment.rst → .../packages/interfaces/class-enrichment.rst
diff --git a/docs/interfaces/dumper.rst → docs/packages/interfaces/dumper.rst b/docs/interfaces/dumper.rst → docs/packages/interfaces/dumper.rst
diff --git a/docs/interfaces/index.rst → docs/packages/interfaces/index.rst b/docs/interfaces/index.rst → docs/packages/interfaces/index.rst
diff --git a/docs/interfaces/mapping-provider.rst → .../packages/interfaces/mapping-provider.rst b/docs/interfaces/mapping-provider.rst → .../packages/interfaces/mapping-provider.rst
diff --git a/docs/interfaces/obograph.rst → docs/packages/interfaces/obograph.rst b/docs/interfaces/obograph.rst → docs/packages/interfaces/obograph.rst
diff --git a/docs/interfaces/owl.rst → docs/packages/interfaces/owl.rst b/docs/interfaces/owl.rst → docs/packages/interfaces/owl.rst
diff --git a/docs/interfaces/patcher.rst → docs/packages/interfaces/patcher.rst b/docs/interfaces/patcher.rst → docs/packages/interfaces/patcher.rst
diff --git a/docs/interfaces/relation-graph.rst → docs/packages/interfaces/relation-graph.rst b/docs/interfaces/relation-graph.rst → docs/packages/interfaces/relation-graph.rst
diff --git a/docs/interfaces/search.rst → docs/packages/interfaces/search.rst b/docs/interfaces/search.rst → docs/packages/interfaces/search.rst
diff --git a/docs/interfaces/semantic-similarity.rst → ...ckages/interfaces/semantic-similarity.rst b/docs/interfaces/semantic-similarity.rst → ...ckages/interfaces/semantic-similarity.rst
diff --git a/docs/interfaces/subsetting.rst → docs/packages/interfaces/subsetting.rst b/docs/interfaces/subsetting.rst → docs/packages/interfaces/subsetting.rst
diff --git a/docs/interfaces/summary-statistics.rst → ...ackages/interfaces/summary-statistics.rst b/docs/interfaces/summary-statistics.rst → ...ackages/interfaces/summary-statistics.rst
diff --git a/docs/interfaces/text-annotator.rst → docs/packages/interfaces/text-annotator.rst b/docs/interfaces/text-annotator.rst → docs/packages/interfaces/text-annotator.rst
diff --git a/docs/interfaces/validator.rst → docs/packages/interfaces/validator.rst b/docs/interfaces/validator.rst → docs/packages/interfaces/validator.rst
diff --git a/docs/selectors.rst → docs/packages/selectors.rst b/docs/selectors.rst → docs/packages/selectors.rst
@@ -1,6 +1,6 @@
 .. _selectors:
 
-Ontology Implementation Selectors
+Ontology Adapter Selectors
 =================
 
 In the command line interface and in Python code, *descriptors* can be used as a shorthand way to refer to either a local or remote ontology, plus
@@ -11,8 +11,8 @@ to instantiate an implementation. The descriptors can also be used in the :ref:`
 
     Ontologies are available in a sometimes bewildering range of formats. One thing that constantly
     trips people up is the distinction between ontology *language* and *serialization*. OWL is an ontology
-    language, *not* a syntax. OWL has its own syntaxes such as Manchester, OWL-XML and Functional -- additionally
-    it can be *mapped* to RDF, which is its *own* datamodel/language, with its *own* serializations (Turtle,
+    language, *not* a syntax. OWL has its own syntaxes such as :term:`Manchester Syntax`, OWL-XML and :term:`Functional Syntax' -- additionally
+    it can be *mapped* to RDF, which is its *own* datamodel/language, with its *own* serializations (:term:`Turtle`,
     RDF/XML (NOT the same as OWL-XML), JSON-LD, ...). Confusing, huh? We are doing our best in this library
     to simplify things for you the user, please be patient!
 
@@ -29,10 +29,10 @@ Examples
 
 Examples of scheme-less descriptors, implicit implementation:
 
-- :code:`tests/input/go-nucleus.obo` - local obo format file loaded with pronto
-- :code:`tests/input/go-nucleus.json` - local obojson format file loaded with pronto
+- :code:`tests/input/go-nucleus.obo` - local :term:`OBO Format` file loaded with pronto
+- :code:`tests/input/go-nucleus.json` - local :term:`OBO Graphs` json format file loaded with pronto
 - :code:`tests/input/go-nucleus.owl` - local OWL rdf/xml format file (loaded with rdflib at the moment, may change)
-- :code:`tests/input/go-nucleus.owl.ttl` - local OWL turtle format file (loaded with rdflib at the moment, may change)
+- :code:`tests/input/go-nucleus.owl.ttl` - local OWL :term:`Turtle` file (loaded with rdflib at the moment, may change)
 - :code:`tests/input/go-nucleus.db` - local sqlite3 db loaded with SqlImplementation
 - :code:`http://purl.obolibrary.org/obo/pato.obo` - NOT IMPLEMENTED; download locally for now
 - :code:`http://purl.obolibrary.org/obo/pato.owl` - NOT IMPLEMENTED; download locally for now
@@ -41,21 +41,23 @@ Examples of explicit schemes:
 
 - :code:`sparql:tests/input/go-nucleus.owl.ttl` - local OWL file in turtle serialization
 - :code:`sparql:tests/input/go-nucleus.owl` - local OWL file (RDF/XML assumed unless explicit format option passed)
-- :code:`pronto:tests/input/go-nucleus.obo` - local obo format file loaded with pronto
-- :code:`pronto:tests/input/go-nucleus.json` - local obojson format file loaded with pronto
+- :code:`pronto:tests/input/go-nucleus.obo` - local :term:`OBO Format` file loaded with pronto
+- :code:`pronto:tests/input/go-nucleus.json` - local :term:`OBO Graphs` json format file loaded with pronto
 - :code:`pronto:tests/input/go-nucleus.owl` - local OWL rdf/xml format file (loaded with pronto at the moment may change)
 - :code:`pronto:tests/input/go-nucleus.db` - local sqlite3 db loaded with SqlImplementation
-- :code:`prontolib:pato.obo` - remote obo format file loaded from OBO Library with pronto
+- :code:`prontolib:pato.obo` - remote :term:`OBO Format` file loaded from OBO Library with pronto
 - :code:`prontolib:pato.owl` - remote owl format file loaded from OBO Library with pronto
+- :code:`sqlite:tests/input/go-nucleus.db` - local SQLite file
 - :code:`sqlite:tests/input/go-nucleus.owl` - convert OWL to SQLite and query using sql_implementation
+- :code:`sqlite:obo:go` - pre-made SQLite from :term:`Semantic SQL` registry
 - :code:`bioportal:` all of bioportal
-- :code:`bioportal:pato` pato in bioportal (NOT IMPLEMENTED)
+- :code:`bioportal:pato` pato in bioportal
 - :code:`ontobee:` all of ontobee
-- :code:`ontobee:pato` pato in ontobee (NOT IMPLEMENTED)
+- :code:`ontobee:pato` pato in ontobee
 - :code:`ols:` all of OLS
 - :code:`ols:pato` pato in OLS (NOT IMPLEMENTED)
 - :code:`ubergraph:` all of OLS
-- :code:`ubergraph:pato` pato in ubergraph (NOT IMPLEMENTED)
+- :code:`ubergraph:pato` pato in ubergraph
 
 See :ref:`cli` for more examples
 

diff --git a/docs/utilities.rst → docs/packages/utilities.rst b/docs/utilities.rst → docs/packages/utilities.rst
@@ -6,11 +6,6 @@ Where possible, this library uses simple standalone python functions organized i
 Note: some of these may involve iterated calls on a remote backend, these are candidates for
 being turned into :ref:`interfaces`.
 
-.. currentmodule:: oaklib
-   :toctree: src
-
-   selector
-
 .. currentmodule:: oaklib.utilities
 
 .. autosummary::