Improve documentation

.github/workflows/pages.yml

@@ -24,27 +24,23 @@ jobs:
       with:
         python-version: 3.9
 
-    - name: Install Python dependencies
-      run: |
-        python3 -m pip install sphinx sphinx-copybutton sphinx-rtd-theme
-
-    - name: Generate examples and build documentation
+    - name: Build documentation
       run: |
         ## Init the target folder. 
         # We will put all site documentation there.
         mkdir -p gh-pages
         touch gh-pages/.nojekyll
 
         function build_docs {
-          # The function will checkout a branch and build the Javadoc & documentation 
-          # into provided documentation directory.
+          # The function will checkout a branch `BRANCH` and build the documentation 
+          # into the provided documentation directory `DOCDIR`.
           BRANCH=${1}
           DOCDIR=${2}
 
           git checkout ${BRANCH}
           git fetch
           git pull
-          python3 -m pip install .[dev]
+          python3 -m pip install .[docs]
 
           ## Init the target folder.
           # We will put all site documentation there.
@@ -53,17 +49,17 @@ jobs:
           ## Build the docs
           # Generate the HTML pages and move the generated content into the target folder.
           printf "Building the %s documentation\n" ${DOCDIR}
-
-          sphinx-apidoc --separate --module-first -d 2 -H "API reference" --follow-links -o docs/apidocs src/hpotk
           cd docs
-          make doctest html
+          sphinx-apidoc --separate --module-first -d 2 -H "API reference" --follow-links -o apidocs ../src/hpotk
+          make clean html
 
           mv _build/html/* ../gh-pages/${DOCDIR}
           cd ..
         }
 
         # We store the docs for `main` in `stable` dir
-        build_docs main stable
+        # TODO - re-enable before deploying a version. 
+        #build_docs main stable
         # We store the docs for `development` in `latest` dir
         build_docs development latest
 

.github/workflows/python_ci.yml

@@ -1,7 +1,4 @@
 name: CI
-##
-# Add the line below to README.md and the badge will come alive when the repo is public.
-# [![CI](https://github.com/TheJacksonLaboratory/hpo-toolkit/workflows/CI/badge.svg)](https://github.com/TheJacksonLaboratory/hpo-toolkit/actions/workflows/python_ci.yml)
 
 on:
     push:
@@ -27,8 +24,13 @@ jobs:
             python-version: ${{ matrix.python }}
         - name: Install hpo-toolkit
           run: |
-            python3 -m pip install .[dev]
+            python3 -m pip install .[test,docs]
         - name: Run tests
           run: |
             python3 -m unittest discover -s src -p _test*.py
-            python3 -m unittest discover -s tests
+            python3 -m unittest discover -s tests
+        - name: Run documentation tests
+          run: |
+            cd docs
+            sphinx-apidoc --separate --module-first -d 2 -H "API reference" -o apidocs ../src/hpotk
+            make doctest

README.md

@@ -6,12 +6,26 @@
 
 A toolkit for working with Human Phenotype Ontology in Python.
 
+Loading HPO is as simple as:
+
 ```python
 import hpotk
 
 hpo = hpotk.load_ontology('http://purl.obolibrary.org/obo/hp.json')
+```
+
+Loading HPO annotations is accomplished by running:
+
+```python
+from hpotk.annotations.load.hpoa import SimpleHpoaDiseaseLoader
+
+hpoa_path = 'https://github.com/obophenotype/human-phenotype-ontology/releases/download/v2023-10-09/phenotype.hpoa'
+
+loader = SimpleHpoaDiseaseLoader(hpo)
+diseases = loader.load(hpoa_path)
 
-# Now it's up to you! :)
+# Phenotype annotations for 12,468 rare diseases is at your fingertips.
+assert len(diseases) == 12_468
 ```
 
 Check out the User guide and the API reference for more info:

docs/index.rst

@@ -4,15 +4,14 @@ Welcome to HPO Toolkit's documentation!
 A toolkit for working with Human Phenotype Ontology in Python.
 
 See :ref:`setup` to learn how to install the library into your environment. Check out the :ref:`user-guide` to see
-library use cases and examples, or explore the `API documentation <apidocs/hpotk.html>`_ for a comprehensive technical
-info.
+library use cases and examples, or explore the `API reference <apidocs/hpotk.html>`_ for a comprehensive technical info.
 
 .. toctree::
    :maxdepth: 1
    :caption: Contents:
 
    setup
-   user-guide
+   user-guide/index
    apidocs/modules
 
 

docs/setup.rst

@@ -13,19 +13,32 @@ Installing HPO toolkit is easy - we publish the releases on `PyPi <https://pypi.
 
 Therefore, the latest stable release can be installed by running::
 
-  $ python3 -m pip install hpo-toolkit
+  python3 -m pip install hpo-toolkit
 
 The bleeding edge code
 ^^^^^^^^^^^^^^^^^^^^^^
 
 To access the bleeding edge features, the development version can be installed by::
 
-  $ git clone https://github.com/TheJacksonLaboratory/hpo-toolkit.git
-  $ cd hpo-toolkit
-  $ git checkout development && git pull
-  $ python3 -m pip install .
+  git clone https://github.com/TheJacksonLaboratory/hpo-toolkit.git
+  cd hpo-toolkit
+  git checkout development && git pull
+  python3 -m pip install .
 
 This will clone the Git repository into your machine, switch to the `development` branch, and install HPO toolkit into
 the active Python environment, assuming you have privileges to install packages.
 
+Run tests
+^^^^^^^^^
+
+The contributors may want to run the unit tests and the integration tests to ensure the features work as expected.
+Hpo-toolkit's tests use a combination of `unittest` and `ddt`. The tests are run as::
+
+  python3 -m unittest discover -s src -p _test*.py
+  python3 -m unittest discover -s tests
+
+.. note::
+
+  The library *must* be installed in the environment before running the tests. Otherwise, the test discovery will fail.
+
 That's about it!

docs/user-guide.rst → docs/user-guide/index.rst

@@ -4,13 +4,14 @@
 User guide
 ==========
 
-This guide includes self-contained tutorials for using HPO toolkit to work with Human Phenotype Ontology applications.
+This guide includes self-contained tutorials for using HPO toolkit to work with Human Phenotype Ontology.
 
 .. toctree::
   :maxdepth: 1
   :caption: Contents:
 
   load-ontology
   use-hierarchy
+  load-hpo-annotations
   sort-term-ids
 

docs/user-guide/load-hpo-annotations.rst

@@ -0,0 +1,110 @@
+.. _load-hpo-annotations:
+
+===============
+HPO annotations
+===============
+
+The HPO projects offers phenotype annotations to describe the connection between diseases and HPO terms.
+The annotations are available for download from `HPO annotation release <https://hpo.jax.org/app/data/annotations>`_
+site in tabular format.
+
+
+Load HPO annotations
+^^^^^^^^^^^^^^^^^^^^
+
+HPO toolkit provides means to parse and work with the disease models
+and here we show how to load the HPO annotation file.
+
+The loader needs HPO to Q/C the annotations, hence we must load HPO first. We need the HPO version corresponding
+to the annotations version, although a more recent HPO version should generally work as well.
+
+.. doctest:: hpoa-io
+
+  >>> import hpotk
+
+  >>> base_url = 'https://github.com/obophenotype/human-phenotype-ontology/releases/download/v2023-10-09/'
+  >>> hpo = hpotk.load_minimal_ontology(base_url + 'hp.json')
+
+Now, we can load a the annotation file.
+
+.. doctest:: hpoa-io
+
+  >>> from hpotk.annotations.load.hpoa import SimpleHpoaDiseaseLoader
+
+  >>> loader = SimpleHpoaDiseaseLoader(hpo)
+  >>> diseases = loader.load(base_url + 'phenotype.hpoa')
+  >>> diseases.version
+  '2023-10-09'
+  >>> len(diseases)
+  12468
+
+We loaded `diseases`, an instance of :class:`hpotk.annotations.HpoDiseases` with `12468` disease models.
+
+Now, we can iterate over all diseases:
+
+.. doctest:: hpoa-io
+
+  >>> sum(1 for disease in diseases)
+  12468
+
+ or we can get a disease for a given identifier:
+
+.. doctest:: hpoa-io
+
+  >>> disease = diseases['OMIM:256000']
+  >>> disease.name
+  'Leigh syndrome'
+
+The identifier can be a CURIE `str` (above) or a :class:`hpotk.model.TermId`:
+
+.. doctest:: hpoa-io
+
+  >>> disease = diseases[hpotk.TermId.from_curie('OMIM:256000')]
+  >>> disease.name
+  'Leigh syndrome'
+
+
+Disease model
+^^^^^^^^^^^^^
+
+HPO toolkit provides :class:`hpotk.annotations.HpoDisease` to model the disease data. `HpoDisease` is a simple
+data class with a limited functionality on top of just providing the data. Let's check out the available attributes.
+
+We can access the identifier and name of the disease:
+
+.. doctest:: hpoa-io
+
+  >>> str(disease.identifier)
+  'OMIM:256000'
+  >>> disease.name
+  'Leigh syndrome'
+
+We can access the phenotype annotations of the disease. In case of `Leigh disease` there are `30` annotations:
+
+.. doctest:: hpoa-io
+
+  >>> len(disease.annotations)
+  30
+
+Let's examine the first annotation in greater detail:
+
+.. doctest:: hpoa-io
+
+  >>> a = next(iter(disease.annotations))
+  >>> str(a.identifier)
+  'HP:0000486'
+  >>> hpo.get_term_name(a)
+  'Strabismus'
+
+.. seealso::
+
+  See :class:`hpotk.annotations.HpoDiseaseAnnotation` for more details on the phenotype annotations.
+
+We can also access the modes of inheritance:
+
+.. doctest:: hpoa-io
+
+  >>> for moi in sorted(disease.modes_of_inheritance):
+  ...   print(moi, hpo.get_term_name(moi))
+  HP:0000007 Autosomal recessive inheritance
+  HP:0001427 Mitochondrial inheritance