feat: set-up docsite (#99)

## Reason for Change

- #11

## Changes

- renamed constants.py to _constants.py to not expose constants in API
docs
- use pdoc to generate documentation based on docstring
- add gha to deploy docsite changes on merge to main

## Testing steps
- update GHA to test that docsite won't break as a 'push test', but only
deploy new site on merge to main


## Notes for Reviewer
- tidying up docstrings, adding more README infos and markdowns
- versioning support > not including at this time.
- pdoc docs: https://pdoc.dev/docs/pdoc.html#add-documentation

---------

Co-authored-by: Bento007 <[email protected]>
Co-authored-by: Trent Smith <[email protected]>

.github/workflows/build-docs.yml

@@ -0,0 +1,40 @@
+name: Build Docsite
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: |
+          cd api/python
+          make docs/install
+      - name: Build the docsite
+        run: |
+          cd api/python
+          make docs/build
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: api/python/docs/
+
+  # Deploy the artifact to GitHub pages.
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/push-tests.yml

@@ -123,3 +123,30 @@ jobs:
           files: ./coverage.xml
           flags: unittests
           name: codecov-umbrella
+
+  test-doc-generation:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.ref }}
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+      - name: Python cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/api/python/pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+      - name: Install dependencies
+        run: |
+          cd api/python
+          make docs/install
+      - name: Test pdoc
+        run: |
+          cd api/python
+          make docs/build

README.md

@@ -5,7 +5,7 @@
 
 # CellxGene Ontology Guide
 
-CellxGene Ontology Guide is a filtered and currated collection of ontological metadata from different public sources.
+CellxGene Ontology Guide is a filtered and curated collection of ontological metadata from different public sources.
 The primary goal is to serve the ontology needs of the [CellxGene](https://cellxgene.cziscience.com/) project and its
 associated tools. An [API](./api) for querying the data is also provided.
 

api/python/Makefile

@@ -6,6 +6,15 @@ install: package-data
 install-dev: package-data
 	pip install -e .[test]
 
+docs/install: package-data
+	pip install -e .[docs]
+
+docs/local:
+	pdoc src/cellxgene_ontology_guide
+
+docs/build:
+	pdoc --output-dir docs/ src/cellxgene_ontology_guide
+
 uninstall:
 	pip uninstall -y cellxgene-ontology-guide
 

api/python/README.md

@@ -1,20 +1,35 @@
 # Python API
 
-# Install
+API Documentation: https://chanzuckerberg.github.io/cellxgene-ontology-guide/cellxgene_ontology_guide.html
+
+pypi: https://pypi.org/project/cellxgene-ontology-guide/
+
+# Developer Setup
+
+## Install
 
 ```bash
 make install
 ```
 
-# Uninstall
+## Uninstall
 
 ```bash
 make uninstall
 ```
 
-# Run Unit Tests
+## Run Unit Tests
 
 ```bash
 make install-dev
 make unit-tests
 ```
+
+## Release
+
+The [release.yml](../../.github/workflows/release.yml) GHA should handle the release process for the pypi package.
+However if you need to manually release the package, you can use the following commands:
+
+```bash
+make release/pypi
+```

api/python/pypi_README.md

@@ -0,0 +1 @@
+API Documentation: https://chanzuckerberg.github.io/cellxgene-ontology-guide/cellxgene_ontology_guide.html

api/python/pyproject.toml

@@ -5,17 +5,34 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "cellxgene_ontology_guide"
 dynamic = ["version"]
-description = "Access ontology data used by CZ cellxgene"
+description = "Access ontology metadata used by CZ cellxgene"
 authors = [
     { name = "Chan Zuckerberg Initiative Foundation", email = "[email protected]" }
 ]
 license = { file = "LICENSE" }
-readme = "README.md"
+readme = "pypi_README.md"
 requires-python = "~= 3.10"
 dependencies = ["semantic_version>=2.10.0,<3"]
 
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Build Tools",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12"
+]
+
+[project.urls]
+Documentation = "https://chanzuckerberg.github.io/cellxgene-ontology-guide/cellxgene_ontology_guide.html"
+Repository = "https://github.com/chanzuckerberg/cellxgene-ontology-guide.git"
+Issues = "https://github.com/chanzuckerberg/cellxgene-ontology-guide/issues"
+Changelog = "https://github.com/chanzuckerberg/cellxgene-ontology-guide/blob/main/api/python/CHANGELOG.md"
+
 [project.optional-dependencies]
 test = ["pytest", "coverage"]
+docs = ["pdoc"]
 
 [tool.setuptools.packages.find]
 where = ["src"]
@@ -30,4 +47,3 @@ root = "../.."  # relative to the location of the pyproject.toml file
 
 [tool.pytest.ini_options]
 pythonpath = ["src/cellxgene_ontology_guide"]
-

api/python/src/cellxgene_ontology_guide/__init__.py

@@ -1,3 +1,9 @@
+"""
+.. include:: ../../../../README.md
+.. include:: ../../CHANGELOG.md
+"""
+
 import cellxgene_ontology_guide._version as version
 
 __version__ = version.__version__
+__all__ = ["curated_ontology_term_lists", "entities", "ontology_parser", "supported_versions"]

api/python/src/cellxgene_ontology_guide/ontology_parser.py

@@ -11,6 +11,9 @@ class OntologyParser:
     An object to parse ontology term metadata from ontologies corresponding to a given CellxGene Schema Version.
     """
 
+    cxg_schema: CXGSchema
+    """ CXGSchema object to fetch ontology metadata from """
+
     def __init__(self, schema_version: str):
         """
         Initialize an OntologyParser object with the ontology metadata corresponding to the given CellxGene schema

api/python/src/cellxgene_ontology_guide/supported_versions.py

@@ -44,6 +44,13 @@ def load_supported_versions() -> Any:
 class CXGSchema:
     """A class to represent the ontology information used by a cellxgene schema version."""
 
+    version: str
+    """The schema version used by the class instance."""
+    supported_ontologies: Dict[str, Any]
+    """A dictionary of supported ontologies for the schema version."""
+    ontology_file_names: Dict[str, str]
+    """A dictionary of ontology names and their corresponding file names."""
+
     def __init__(self, version: Optional[str] = None):
         """