docs: Initial docs and JupyterBook setup (#66)

* initial docs and jb setup * style: pre-commit fixes * add rtd workflow .yml * refactor: remove rtd workflow yml * chore: add pixi install to rtd yml * chore: test pixi rtd * chore: change rtd job type * Update .readthedocs.yaml * Update pixi.toml * Update .readthedocs.yaml job commands * chore: remove extra deps file --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Don Setiawan <[email protected]>
uw-ssec · Dec 20, 2024 · b7c507a · b7c507a
1 parent 50811ab
commit b7c507a
Show file tree

Hide file tree

Showing 8 changed files with 1,109 additions and 0 deletions.
diff --git a/.gitignore b/.gitignore
@@ -70,6 +70,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/generated/
 
 # PyBuilder
 .pybuilder/

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,22 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  commands:
+    - asdf plugin add pixi
+    - asdf install pixi latest
+    - asdf global pixi latest
+    - pixi run -e py-phylo2vec build-docs
+    - mkdir -p $READTHEDOCS_OUTPUT/html/
+    - cp -r docs/_build/html/** $READTHEDOCS_OUTPUT/html/
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats: []
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -0,0 +1,39 @@
+# Book settings
+# Learn more at https://jupyterbook.org/customize/config.html
+
+title: Phylo2Vec
+author: Don Setiawan
+# logo: logo.png
+
+# Force re-execution of notebooks on each build.
+# See https://jupyterbook.org/content/execute.html
+execute:
+  execute_notebooks: force
+
+# Define the name of the latex output file for PDF builds
+latex:
+  latex_documents:
+    targetname: book.tex
+
+# Information about where the book exists on the web
+repository:
+  url: https://github.com/uw-ssec/phylo2vec  # Online location of your book
+  path_to_book: docs  # Optional path to your book, relative to the repository root
+  branch: master  # Which branch of the repository should be used when creating links (optional)
+
+# Add GitHub buttons to your book
+# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
+html:
+  use_issues_button: true
+  use_repository_button: true
+
+
+sphinx:
+  extra_extensions:
+  - 'sphinx.ext.autodoc'
+  - 'sphinx.ext.napoleon'
+  - 'sphinx.ext.viewcode'
+  - 'sphinx.ext.autosummary'
+  config:
+    add_module_names: True
+    autosummary_generate: True
diff --git a/docs/_toc.yml b/docs/_toc.yml
@@ -0,0 +1,7 @@
+# Table of contents
+# Learn more at https://jupyterbook.org/customize/toc.html
+
+format: jb-book
+root: intro
+chapters:
+- file: api.rst
diff --git a/docs/api.rst b/docs/api.rst
@@ -0,0 +1,44 @@
+API Reference
+=============
+
+.. currentmodule:: phylo2vec
+
+Base
+----------------
+
+.. autosummary::
+    :nosignatures:
+    :toctree: generated/
+
+    base.to_newick
+    base.to_vector
+
+Metrics
+----------------
+
+.. autosummary::
+    :nosignatures:
+    :toctree: generated/
+
+    metrics.cophenetic_distances
+
+Utils
+----------------
+
+.. autosummary::
+    :nosignatures:
+    :toctree: generated/
+
+    utils.find_num_leaves
+    utils.create_label_mapping
+    utils.apply_label_mapping
+    utils.remove_annotations
+    utils.remove_parent_labels
+    utils.sample
+    utils.seed_everything
+    utils.check_v
+    utils.reorder_v
+    utils.reroot_at_random
+    utils.remove_leaf
+    utils.add_leaf
+    utils.get_common_ancestor
diff --git a/docs/intro.md b/docs/intro.md
@@ -0,0 +1,12 @@
+# Welcome to your Jupyter Book
+
+This is a small sample book to give you a feel for how book content is
+structured. It shows off a few of the major file types, as well as some sample
+content. It does not go in-depth into any particular topic - check out
+[the Jupyter Book documentation](https://jupyterbook.org) for more information.
+
+Check out the content pages bundled with this sample book to see more.
+
+```{tableofcontents}
+
+```
diff --git a/pixi.lock b/pixi.lock
diff --git a/pixi.toml b/pixi.toml
@@ -60,10 +60,15 @@ pip = ">=24.2,<25"
 maturin = ">=1.7.4,<2"
 jupyterlab = ">=4.1,<4.2"
 pytest = ">=8.3.4,<9"
+jupyter-book = ">=0.11.0"
 
 [feature.python.tasks.install-python]
 cmd = "maturin develop --release --manifest-path ./py-phylo2vec/Cargo.toml"
 
+[feature.python.tasks.build-docs]
+cmd = "jupyter-book build docs"
+depends-on = ["install-python"]
+
 [feature.python.tasks.test]
 cmd = "pytest -vvv ./py-phylo2vec/tests"
 depends-on = ["install-python"]