Merge pull request #20 from kazewong/Documentation

Add documentation infrastructure with mkdocs

.gitattributes

@@ -0,0 +1,2 @@
+docs/** linguist-vendored
+notebooks/** linguist-vendored

docs/gen_ref_pages.py

@@ -0,0 +1,33 @@
+"""Generate the code reference pages."""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+
+
+for path in sorted(Path("src").rglob("*.py")):  #
+    module_path = path.relative_to("src").with_suffix("")  #
+    doc_path = path.relative_to("src").with_suffix(".md")  #
+    full_doc_path = Path("api", doc_path)  #
+
+    parts = list(module_path.parts)
+
+    if parts[-1] == "__init__":  #
+        continue
+    elif parts[-1] == "__main__":
+        continue
+
+    nav[parts] = doc_path.as_posix()
+
+    print(full_doc_path)
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:  #
+        identifier = ".".join(parts)  #
+        print("::: " + identifier, file=fd)  #
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path)  #
+
+    with mkdocs_gen_files.open("api/summary.md", "w") as nav_file:  #
+        nav_file.writelines(nav.build_literate_nav())

docs/index.md

@@ -0,0 +1,6 @@
+ripple
+======
+
+**A light weight jax package for differentiable and fast gravitational wave data analysis**
+
+This is a sick package, install it now

docs/notebooks

@@ -0,0 +1 @@
+../notebooks/

docs/requirements.txt

@@ -0,0 +1,14 @@
+flowMC
+jax>=0.4.12
+jaxlib>=0.4.12
+equinox>=0.10.6
+optax>=0.1.5
+evosax>=0.1.4
+tqdm
+mkdocs==1.4.3               # Main documentation generator.
+mkdocs-material==9.1.18     # Theme
+pymdown-extensions==10.1    # Markdown extensions e.g. to handle LaTeX.
+mkdocstrings[python]==0.22.0        # Autogenerate documentation from docstrings.
+mkdocs-jupyter==0.24.2       # Turn Jupyter Lab notebooks into webpages.
+mkdocs-gen-files==0.5.0
+mkdocs-literate-nav==0.6.0

docs/stylesheets/extra.css

@@ -0,0 +1,5 @@
+:root {
+    --md-primary-fg-color:        #200f80;
+    --md-primary-fg-color--light: #6cb8bb;
+    --md-primary-fg-color--dark:  #6cb8bb;
+  }

mkdocs.yml

@@ -0,0 +1,80 @@
+site_name: ripple
+site_description: A light weight jax package for differentiable and fast gravitational wave data analysis.
+site_author: Thomas Edwards, Kaze Wong
+repo_url: https://github.com/tedwards2412/ripple
+repo_name: tedwards2412/ripple
+
+theme:
+    name: material
+    features:
+        - navigation  # Sections are included in the navigation on the left.
+        - toc  # Table of contents is integrated on the left; does not appear separately on the right.
+        - header.autohide  # header disappears as you scroll
+    palette:
+        # Light mode / dark mode
+        # We deliberately don't automatically use `media` to check a user's preferences. We default to light mode as
+        # (a) it looks more professional, and (b) is more obvious about the fact that it offers a (dark mode) toggle.
+        - scheme: default
+          primary: cyan
+          accent: deep purple
+          toggle:
+             icon: material/brightness-5
+             name: Dark mode
+        - scheme: slate
+          primary: custom
+          accent: purple
+          toggle:
+             icon: material/brightness-2
+             name: Light mode
+
+    twitter_name: "@physicskaze"
+    twitter_url: "https://twitter.com/physicskaze"
+
+markdown_extensions:
+    - pymdownx.arithmatex:  # Render LaTeX via MathJax
+        generic: true
+    - pymdownx.superfences  # Seems to enable syntax highlighting when used with the Material theme.
+    - pymdownx.details  
+    - pymdownx.snippets:  # Include one Markdown file into another
+        base_path: docs
+    - admonition
+    - toc:
+        permalink: "¤"  # Adds a clickable permalink to each section heading
+        toc_depth: 4
+
+plugins:
+    - search  # default search plugin; needs manually re-enabling when using any other plugins
+    - autorefs  # Cross-links to headings
+    - mkdocs-jupyter: # Jupyter notebook support
+        # show_input: False
+    - gen-files:
+        scripts:
+        - docs/gen_ref_pages.py
+    - literate-nav:
+        nav_file: SUMMARY.md
+    - mkdocstrings:
+        handlers:
+            python:
+                setup_commands:
+                    - import pytkdocs_tweaks
+                    - pytkdocs_tweaks.main()
+                    - import jaxtyping
+                    - jaxtyping.set_array_name_format("array")
+
+                optional:
+                    inherited_members: true  # Allow looking up inherited methods
+                    show_root_heading: true  # actually display anything at all...
+                    show_root_full_path: true  # display "diffrax.asdf" not just "asdf"
+                    show_if_no_docstring: true
+                    show_signature_annotations: true
+                    show_source: false  # don't include source code
+                    members_order: source  # order methods according to their order of definition in the source code, not alphabetical order
+                    heading_level: 4
+
+extra_css:
+  - stylesheets/extra.css
+
+nav:
+    - Home: index.md
+    - API: api/ripple/*
+    - Tutorial: notebooks/*

readthedocs.yml

@@ -0,0 +1,13 @@
+version: 2
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+mkdocs:
+  configuration: mkdocs.yml