diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml new file mode 100644 index 0000000..a9bddda --- /dev/null +++ b/.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 diff --git a/.github/workflows/push-tests.yml b/.github/workflows/push-tests.yml index 7ef0aac..37e71b2 100644 --- a/.github/workflows/push-tests.yml +++ b/.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 diff --git a/README.md b/README.md index 04b3f7f..d6ddeae 100644 --- a/README.md +++ b/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. diff --git a/api/python/Makefile b/api/python/Makefile index 01862cb..49d8a2f 100644 --- a/api/python/Makefile +++ b/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 diff --git a/api/python/README.md b/api/python/README.md index bf99b50..bc0733e 100644 --- a/api/python/README.md +++ b/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 +``` diff --git a/api/python/pypi_README.md b/api/python/pypi_README.md new file mode 100644 index 0000000..e03a73d --- /dev/null +++ b/api/python/pypi_README.md @@ -0,0 +1 @@ +API Documentation: https://chanzuckerberg.github.io/cellxgene-ontology-guide/cellxgene_ontology_guide.html diff --git a/api/python/pyproject.toml b/api/python/pyproject.toml index b1e973f..86210bb 100644 --- a/api/python/pyproject.toml +++ b/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 = "cellxgene@chanzuckerberg.com" } ] 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"] - diff --git a/api/python/src/cellxgene_ontology_guide/__init__.py b/api/python/src/cellxgene_ontology_guide/__init__.py index 95e5075..ab0ec43 100644 --- a/api/python/src/cellxgene_ontology_guide/__init__.py +++ b/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"] diff --git a/api/python/src/cellxgene_ontology_guide/ontology_parser.py b/api/python/src/cellxgene_ontology_guide/ontology_parser.py index 1e1a320..a366d34 100644 --- a/api/python/src/cellxgene_ontology_guide/ontology_parser.py +++ b/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 diff --git a/api/python/src/cellxgene_ontology_guide/supported_versions.py b/api/python/src/cellxgene_ontology_guide/supported_versions.py index e2eace1..ca38811 100644 --- a/api/python/src/cellxgene_ontology_guide/supported_versions.py +++ b/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): """