Merge pull request #36 from TheJacksonLaboratory/setup-docs

Setup the documentation.

.github/workflows/pages.yml

@@ -0,0 +1,77 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy documentation to GitHub Pages
+
+on:
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+  # Runs on pushes targeting the main branch
+  push:
+    branches: [ main, development ]
+  pull_request:
+    branches: [ development ]
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v3
+      with:
+        fetch-depth: 0 # otherwise, you will fail to push refs to dest repo
+        ref: main
+
+    - name: Set up Python 3.
+      uses: actions/setup-python@v4
+      with:
+        python-version: 3.9
+
+    - name: Install Python dependencies
+      run: |
+        pip install sphinx
+        pip install sphinx-rtd-theme
+
+    - name: Generate examples and 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.
+          BRANCH=${1}
+          DOCDIR=${2}
+        
+          git checkout ${BRANCH}
+          git fetch
+          git pull
+          ## Init the target folder.
+          # We will put all site documentation there.
+          mkdir -p gh-pages/${DOCDIR}
+        
+          ## 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 documentation" --follow-links -o docs/apidocs src/hpotk
+          cd docs
+          make html
+          
+          mv _build/html/* gh-pages/${DOCDIR}
+        }
+        
+        # We store the docs for `master` in `stable` dir
+        build_docs main stable
+        # We store the docs for `develop` in `latest` dir
+        build_docs development latest
+
+
+    - name: Deploy documentation.
+      if: ${{ github.event_name == 'push' }}
+      uses: JamesIves/github-pages-deploy-action@v4.4.1
+      with:
+        branch: gh-pages
+        force: true
+        folder: gh-pages

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,38 @@
+import os
+import sys
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'hpo-toolkit'
+copyright = '2023, Daniel Danis'
+author = 'Daniel Danis'
+release = '0.2.1'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+sys.path.insert(0, os.path.abspath(os.path.join('..', 'src')))
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.napoleon',
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+pygments_style = 'sphinx'
+html_theme = "sphinx_rtd_theme"
+
+html_static_path = ['_static']
+html_css_files = ['hpo-toolkit.css']

docs/index.rst

@@ -0,0 +1,19 @@
+Welcome to hpo-toolkit's documentation!
+=======================================
+
+A toolkit for working with Human Phenotype Ontology in Python.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   setup
+   apidocs/modules
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/setup.rst

@@ -0,0 +1,9 @@
+=====
+Setup
+=====
+
+The docs are still work in progress.
+
+In the meantime, look at the `Tutorial notebook <https://github.com/TheJacksonLaboratory/hpo-toolkit/blob/main/notebooks/Tutorial.ipynb>`_
+and `API documentation <apidocs/modules.html>`_, e.g. :class:`hpotk.model.TermId`, :class:`hpotk.model.MinimalTerm`,
+and :class:`hpotk.ontology.MinimalOntology`.

src/hpotk/__init__.py

@@ -1,3 +1,7 @@
+"""
+See the subpackages and submodules to read about `hpo-toolkit`'s components.
+"""
+
 __version__ = "0.2.1dev0"
 
 from . import algorithm

src/hpotk/algorithm/similarity/__init__.py

@@ -1,3 +1,9 @@
 from ._ic import calculate_ic_for_annotated_items
 from ._model import AnnotationIcContainer, SimpleAnnotationIcContainer, SimilarityContainer
 from ._resnik import precalculate_ic_mica_for_hpo_concept_pairs
+
+__all__ = [
+    'calculate_ic_for_annotated_items',
+    'AnnotationIcContainer', 'SimpleAnnotationIcContainer', 'SimilarityContainer',
+    'precalculate_ic_mica_for_hpo_concept_pairs'
+]

src/hpotk/annotations/__init__.py

@@ -5,3 +5,10 @@
 from ._simple import SimpleHpoDiseaseAnnotation, SimpleHpoDisease, SimpleHpoDiseases
 
 from . import load
+
+__all__ = [
+    'AnnotatedItem', 'AnnotatedItemContainer', 'ANNOTATED_ITEM', 'ANNOTATION',
+    'EvidenceCode', 'Sex', 'AnnotationReference',
+    'HpoDiseaseAnnotation', 'HpoDisease', 'HpoDiseases',
+    'SimpleHpoDiseaseAnnotation', 'SimpleHpoDisease', 'SimpleHpoDiseases'
+]

src/hpotk/annotations/load/hpoa/__init__.py

@@ -1 +1,5 @@
 from ._impl import SimpleHpoaDiseaseLoader
+
+__all__ = [
+    'SimpleHpoaDiseaseLoader'
+]

src/hpotk/graph/__init__.py

@@ -2,3 +2,6 @@
 from ._csr_graph import SimpleCsrOntologyGraph  # REMOVE(v1.0.0)
 from ._factory import CsrGraphFactory  # REMOVE(v1.0.0)
 from ._factory import GraphFactory, IncrementalCsrGraphFactory
+
+__all__ = ['OntologyGraph', 'GraphAware',
+           'GraphFactory', 'IncrementalCsrGraphFactory']

src/hpotk/graph/_api.py

@@ -165,7 +165,7 @@ def _map_to_term_id(item: typing.Union[str, NODE, Identified]) -> TermId:
 
 class GraphAware(typing.Generic[NODE], metaclass=abc.ABCMeta):
     """
-    Base class for entities that have an `OntologyGraph`.
+    Base class for entities that have an :class:`OntologyGraph`.
     """
 
     @property

src/hpotk/graph/_factory.py

@@ -29,6 +29,7 @@ def __init__(self):
     def create_graph(self, edge_list: typing.Sequence[DirectedEdge]) -> GRAPH:
         """
         Create graph from edge list.
+
         :param edge_list: a sequence of `DirectedEdge`s where the first item is the source
                           and the second item is the destination
         :return: the graph

src/hpotk/model/__init__.py

@@ -1,3 +1,7 @@
+"""
+Data structures for modeling ontology data.
+"""
+
 import typing
 
 from ._term_id import TermId
@@ -9,3 +13,7 @@
 CURIE_OR_TERM_ID = typing.Union[str, ID]
 MINIMAL_TERM = typing.TypeVar('MINIMAL_TERM', bound=MinimalTerm)
 TERM = typing.TypeVar('TERM', bound=Term)
+
+__all__ = ['TermId',
+           'Identified', 'ObservableFeature', 'FrequencyAwareFeature', 'Named', 'Versioned', 'MetadataAware',
+           'MinimalTerm', 'Term', 'Synonym', 'SynonymType', 'SynonymCategory']

src/hpotk/model/_base.py

@@ -14,7 +14,9 @@ class Identified(metaclass=abc.ABCMeta):
     @abc.abstractmethod
     def identifier(self) -> TermId:
         """
-        :return: the identifier of the entity.
+        Get the entity identifier.
+
+        :return: the identifier of the entity
         """
         pass
 
@@ -29,6 +31,8 @@ class ObservableFeature(metaclass=abc.ABCMeta):
     @abc.abstractmethod
     def is_present(self) -> bool:
         """
+        Test if the feature was observed in one or more items.
+
         :return: `True` if the feature was observed in one or more items.
         """
         pass
@@ -43,7 +47,9 @@ def is_absent(self) -> bool:
     @property
     def is_excluded(self) -> bool:
         """
-        :return: `True` if the feature was observed in none of the annotated item(s), and therefore, excluded.
+        Test if the feature was not observed in any of the items.
+
+        :return: `True` if the feature was observed in *none of the annotated item(s), and therefore, excluded.
         """
         return not self.is_present
 
@@ -69,16 +75,21 @@ class FrequencyAwareFeature(ObservableFeature, metaclass=abc.ABCMeta):
     @abc.abstractmethod
     def numerator(self) -> int:
         """
-        :return: a non-negative `int` representing the count of annotated items where the annotation was present.
+        Get the numerator, a non-negative `int` representing the count of annotated items where the annotation
+        was present.
+
+        :return: the numerator.
         """
         pass
 
     @property
     @abc.abstractmethod
     def denominator(self) -> int:
         """
-        :return: a positive `int` representing the total count of annotated items investigated
+        Get the denominator, a positive `int` representing the total count of annotated items investigated
         for presence/absence of an annotation.
+
+        :return: the denominator.
         """
         pass
 
@@ -92,14 +103,14 @@ def frequency(self) -> float:
     @property
     def is_present(self) -> bool:
         """
-        :return: `True` if the annotation was observed in one or more items.
+        Test if the annotation was observed in one or more items.
         """
         return self.numerator != 0
 
     @property
     def is_excluded(self) -> bool:
         """
-        :return: `True` if the annotation was observed in none of the annotated item(s), and therefore, excluded.
+        Test if the annotation was observed in none of the annotated item(s), and therefore, excluded.
         """
         return self.numerator == 0
 
@@ -126,7 +137,9 @@ class Named(metaclass=abc.ABCMeta):
     @abc.abstractmethod
     def name(self) -> str:
         """
-        :return: the human-readable name of the entity
+        Get a human-friendly name of the entity.
+
+        :return: the human-readable name of the entity.
         """
         pass
 
@@ -154,13 +167,15 @@ class MetadataAware(metaclass=abc.ABCMeta):
     @abc.abstractmethod
     def metadata(self) -> typing.MutableMapping[str, str]:
         """
-        :return: a mapping with entity metadata.
+        Get a mapping with entity metadata.
+
+        :return: the mapping.
         """
         pass
 
     def metadata_to_str(self) -> str:
         """
-        Dump the metadata to a single string.
+        Dump the metadata to a `str`.
         """
         forbidden = {';', '='}
         for k, v in self.metadata.items():
@@ -172,7 +187,7 @@ def metadata_to_str(self) -> str:
     @staticmethod
     def metadata_from_str(value: str) -> typing.Mapping[str, str]:
         """
-        Load the metadata from `str` created by `metadata_to_str`.
+        Load the metadata from `str` created by `metadata_to_str()`.
         """
         data = {}
         for item in value.split(';'):