docs: Update docs with Jupyter Book and NumPy docstrings (#110)

This is a PR from uw-ssec#25. This improved the documentation to use Jupyter Book instead of vanilla sphinx. Google docstring style has been updated to Numpy docstring style. --- Ref: uw-ssec#11 Original author: https://github.com/sophietao127 - docs: Add tutorials - Added index.md to tutorials - Updated _config.yml and _toc.yml - docs: Lint docs and update notebooks --------- Co-authored-by: Landung 'Don' Setiawan <[email protected]>
Ciela-Institute · Dec 8, 2023 · 541f265 · 541f265
1 parent 2b2ef5b
commit 541f265
Show file tree

Hide file tree

Showing 59 changed files with 4,017 additions and 1,434 deletions.
diff --git a/.devcontainer/postBuild.sh b/.devcontainer/postBuild.sh
@@ -1,5 +1,5 @@
 # For writing commands that will be executed after the container is created
 
-# Installs `caustic` as local library without resolving dependencies (--no-deps)
+# Installs `caustics` as local library without resolving dependencies (--no-deps)
 python3 -m pip install -e /workspaces/caustics --no-deps
 python3 -m pip install -e ".[dev]"
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -11,8 +11,9 @@ install `nox`:
 
 ## Codespaces
 
-Nox is pre-installed in the Codespaces environment. So, after activating a Codespace,
-you can just open the terminal and run `nox` to run all the checks and tests.
+Nox is pre-installed in the Codespaces environment. So, after activating a
+Codespace, you can just open the terminal and run `nox` to run all the checks
+and tests.
 
 ## Local
 
@@ -32,10 +33,9 @@ brew install nox
 
 ### What is it?
 
-`nox` is a command-line tool that automates testing in multiple Python environments,
-similar to tox. Unlike tox,
-Nox uses a standard Python file for configuration,
-you can find this configuration in [`noxfile.py`](../noxfile.py).
+`nox` is a command-line tool that automates testing in multiple Python
+environments, similar to tox. Unlike tox, Nox uses a standard Python file for
+configuration, you can find this configuration in [`noxfile.py`](../noxfile.py).
 
 ### How do I use it?
 

diff --git a/.gitignore b/.gitignore
@@ -137,3 +137,7 @@ package.json
 
 # version
 _version.py
+
+# Jupyter book
+conf.py
+caustics*.rst
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,8 +1,7 @@
 exclude: |
   (?x)^(
     tests/utils.py |
-    .devcontainer/ |
-    docs/source/
+    .devcontainer/
   )
 
 ci:
@@ -77,6 +76,12 @@ repos:
     hooks:
       - id: shellcheck
 
+  - repo: https://github.com/kynan/nbstripout
+    rev: 0.6.1
+    hooks:
+      - id: nbstripout
+        args: [--extra-keys=metadata.kernelspec metadata.language_info.version]
+
   - repo: local
     hooks:
       - id: disallow-caps

diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -25,10 +25,16 @@ build:
     python: "3.9"
   apt_packages:
     - pandoc # Specify pandoc to be installed via apt-get
+    - graphviz # Specify graphviz to be installed via apt-get
+  jobs:
+    pre_build:
+      # Generate the Sphinx configuration for this Jupyter Book so it builds.
+      - "jupyter-book config sphinx docs/source/"
+      - "sphinx-apidoc -f -o docs/source/ src/caustics/"
 
 python:
   install:
-    - requirements: requirements.txt # Path to your requirements.txt file
     - requirements: docs/requirements.txt # Path to your requirements.txt file
+    - requirements: requirements.txt # Path to your requirements.txt file
     - method: pip
       path: . # Install the package itself
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) [2023] [caustic authors]
+Copyright (c) [2023] [caustics authors]
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/README.md b/README.md
@@ -26,15 +26,15 @@ pip install caustics
 
 ## Documentation
 
-Please see our [documentation page](https://caustics.readthedocs.io/en/latest/) for
-more detailed information.
+Please see our [documentation page](https://caustics.readthedocs.io/en/latest/)
+for more detailed information.
 
 ## Contribution
 
 We welcome contributions from collaborators and researchers interested in our
 work. If you have improvements, suggestions, or new findings to share, please
-submit an issue or pull request. Your contributions help advance our research and analysis
-efforts.
+submit an issue or pull request. Your contributions help advance our research
+and analysis efforts.
 
 To get started with your development (or fork), click the "Open with GitHub
 Codespaces" button below to launch a fully configured development environment

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,4 +1,5 @@
-nbsphinx
+jupyter-book
 sphinx
 sphinx_rtd_theme
-wheel
+matplotlib
+ipywidgets
diff --git a/docs/source/_config.yml b/docs/source/_config.yml
@@ -0,0 +1,47 @@
+# Book settings
+# Learn more at https://jupyterbook.org/customize/config.html
+
+title: Caustics
+author: Ciela Institute
+logo: ../../media/caustics_logo.png
+
+# Force re-execution of notebooks on each build.
+# See https://jupyterbook.org/content/execute.html
+execute:
+  execute_notebooks: force
+  allow_errors: false
+  # Per-cell notebook execution limit (seconds)
+  timeout: 10
+
+# Define the name of the latex output file for PDF builds
+latex:
+  latex_documents:
+    targetname: book.tex
+
+# Add a bibtex file so that we can create citations
+# bibtex_bibfiles:
+#   - references.bib
+
+# Information about where the book exists on the web
+repository:
+  url: https://github.com/Ciela-Institute/caustics # Online location of your book
+  path_to_book: docs/source # Optional path to your book, relative to the repository root
+  branch: main # 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:
+  favicon: ../../media/caustics_favicon.ico
+  use_issues_button: true
+  use_repository_button: true
+
+sphinx:
+  extra_extensions:
+    - "sphinx.ext.autodoc"
+    - "sphinx.ext.autosummary"
+    - "sphinx.ext.napoleon"
+    - "sphinx.ext.doctest"
+    - "sphinx.ext.coverage"
+    - "sphinx.ext.mathjax"
+    - "sphinx.ext.ifconfig"
+    - "sphinx.ext.viewcode"
diff --git a/docs/source/_toc.yml b/docs/source/_toc.yml
@@ -0,0 +1,21 @@
+# Table of contents
+# Learn more at https://jupyterbook.org/customize/toc.html
+
+format: jb-book
+root: intro
+chapters:
+  - file: getting_started
+  - file: install
+  - file: tutorials/index
+    sections:
+      - file: tutorials/BasicIntroduction
+      - file: tutorials/LensZoo
+      - file: tutorials/VisualizeCaustics
+      - file: tutorials/MultiplaneDemo
+      - file: tutorials/InvertLensEquation
+      - file: tutorials/Simulators
+      - file: tutorials/Playground
+  - file: contributing
+  - file: citation
+  - file: license
+  - file: modules
diff --git a/docs/source/citation.rst b/docs/source/citation.rst
@@ -3,4 +3,4 @@
 Citation
 ========
 
-Paper comming soon! We will put all the citation information here when its ready.
+Paper coming soon! We will put all the citation information here when its ready.
diff --git a/docs/source/conf.py b/docs/source/conf.py
diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst
@@ -9,7 +9,7 @@ Thanks for helping make caustics better! Here you will learn the full process ne
 Create An Issue
 ---------------
 
-Before actually writing any code, its best to create an issue on the GitHub. Describe the issue in detail and let us know the desired solution. Here it will be possible to address concerns (maybe its aready solved and just not yet documented) and plan out the best solution. We may also assign someone to work on it if that seems better. Note that submitting an issue is a contribution to caustics, we appreciate your ideas! Still, if after discussion it seems that the problem does need some work and you're the person to do it, then we can move on to the next steps.
+Before actually writing any code, its best to create an issue on the GitHub. Describe the issue in detail and let us know the desired solution. Here it will be possible to address concerns (maybe its already solved and just not yet documented) and plan out the best solution. We may also assign someone to work on it if that seems better. Note that submitting an issue is a contribution to caustics, we appreciate your ideas! Still, if after discussion it seems that the problem does need some work and you're the person to do it, then we can move on to the next steps.
 
 1. Navigate to the **Issues** tab of the GitHub repository.
 2. Click on **New Issue**.

diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst
@@ -17,4 +17,4 @@ We have created a repository of tutorial Jupyter notebooks that can help initiat
 Read The Docs
 -------------
 
-Docs for all the main functions in caustics are avaialble at :doc:`caustics` at varying degrees of completeness. Further development of the docs is always ongoing.
+Docs for all the main functions in caustics are available at :doc:`caustics` at varying degrees of completeness. Further development of the docs is always ongoing.