docs: Initial docs and JupyterBook setup

.gitignore

@@ -70,6 +70,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/generated/
 
 # PyBuilder
 .pybuilder/

.readthedocs.yaml

@@ -0,0 +1,23 @@
+# .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"
+  jobs:
+    install:
+      - 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: []

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

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

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

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}
+
+```

docs/requirements.txt

@@ -0,0 +1 @@
+jupyter-book

pixi.toml

@@ -60,10 +60,14 @@ 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 --manifest-path ./py-phylo2vec/Cargo.toml"
 
+[feature.python.tasks.build-docs]
+cmd = "jupyter-book build docs"
+
 [feature.python.tasks.test]
 cmd = "pytest -vvv ./py-phylo2vec/tests"
 depends-on = ["install-python"]