feat: set-up docsite

[nayib-jose-gloria]

Reason for Change

• feat(API): Document API #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

[Bento007]

add this to pyproject.yaml

[project.optional-dependencies]
test = ["pytest"]
docs = ["pydoc"]

Then change this make recipe to

install-docs:
	pip install .[docs]

[Bento007]

I made a sphinx version of the docs, and it was a lot more work and still doesn't look as good as the pdoc version. If we host on readthedocs we get the versioning for free, but that requires a subscription. Sphinx doesn't support it out of the box and will require additional configuration to work. For now I think this is good enough. We should host the latest at least and can add instructions that the users can follow to generate docs for older versions.

[nayib-jose-gloria]

not sure where the docsite homepage description is being set, but there is a typo:

"CellxGene Ontology Guide is a filtered and currated collection of ontological metadata from different public sources"

[nayib-jose-gloria]

Data submodule page is empty on the docsite as well, we should probably find a way to not include it since its an internal directory anyway

[nayib-jose-gloria]

https://chanzuckerberg.github.io/cellxgene-ontology-guide/cellxgene_ontology_guide/ontology_parser.html#OntologyParser.cxg_schema

weird non-definition for this attribute here

[nayib-jose-gloria]

non-definitions of attributes here as well https://chanzuckerberg.github.io/cellxgene-ontology-guide/cellxgene_ontology_guide/supported_versions.html#CXGSchema.supported_ontologies

[nayib-jose-gloria]

looks good overall, just a few things to fix

In a separate ticket, we should document (in the repo, not docsite) the release process + changelog best practices for contributors

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 83.89%. Comparing base (c52c436) to head (4b0eaf6).

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #99      +/-   ##
==========================================
+ Coverage   83.73%   83.89%   +0.15%     
==========================================
  Files          18       18              
  Lines         916      925       +9     
  Branches      176      176              
==========================================
+ Hits          767      776       +9     
  Misses        139      139              
  Partials       10       10              

Flag	Coverage Δ
unittests	83.89% <100.00%> (+0.15%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[nayib-jose-gloria]

LGTM!