mehta-lab · amitabhverma · Aug 26, 2025 · Jun 4, 2025 · Jul 18, 2025 · Jul 18, 2025
diff --git a/.gitignore b/.gitignore
@@ -2,7 +2,6 @@
 *.tif[f]
 *.jp[e]g
 *.zar[r]
-*.json
 
 # pycharm IDE
 .idea
@@ -19,6 +18,8 @@ __pycache__/
 # Distribution / packaging
 .Python
 build/
+docs/build/
+docs/wo_examples/
 develop-eggs/
 dist/
 downloads/
@@ -148,7 +149,6 @@ waveorder/_version.py
 
 # images
 *.npz
-*.png
 *.tif[f]
 *.pdf
 

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,28 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+  jobs:
+    post_build:
+      - python docs/scripts/fix_md_links.py
+
+# Optionally, but recommended,
+# declare the Python requirements required to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -50,7 +50,6 @@ pip install -e ".[dev]"
 
 Then make the changes and [track them with Git](https://docs.github.com/en/get-started/using-git/about-git#example-contribute-to-an-existing-repository).
 
-
 ### Code style
 
 We use [pre-commit](https://pre-commit.com/) to sort imports with [isort](https://github.com/PyCQA/isort) and format code with [black](https://black.readthedocs.io/en/stable/) automatically prior to each commit. To minimize test errors when submitting pull requests, please install pre-commit in your environment as follows:
@@ -60,3 +59,29 @@ pre-commit install
 ```
 
 When these packages are executed within the project root directory, they should automatically use the [project settings](./pyproject.toml).
+
+### Developing documentation
+
+Documentation infrastructure is built using [Markdown (.md)](https://www.sphinx-doc.org/en/master/usage/markdown.html) and [reStructuredText (.rst)](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) files. [Sphinx](https://www.sphinx-doc.org/en/master/index.html) utilizes these to build highly customization .html pages for User Guides, API References and Examples rendered directly from source code files.
+
+#### Building the HTML version locally
+
+```sh
+cd waveorder/ # or the renamed project root directory
+pip install -e ".[docs]"
+```
+
+```shell
+cd docs/
+pip install sphinx
+sphinx-build -M html ./ ./build
+```
+
+Generated HTML documentation can be found in the ``build/html`` directory. Open ``build/html/index.html`` to view the home page for the documentation.
+
+Automated building of `docs` is done via _read-the-docs_ which will automatically pull commits to the `main` branch and host them here: <https://waveorder.readthedocs.io>
+
+#### Documentation change
+
+If you find that any documentation in this project is incomplete, inaccurate, or ambiguous, please open an issue.
+We welcome contributions to the documentation from users, particularly user guides that we can collaboratively edit.
diff --git a/docs/README.md b/docs/README.md
@@ -4,24 +4,25 @@ We have organized our documentation by user type and intended task.
 
 ## Software users
 
-**Reconstruct existing data:** start with the [reconstruction guide](./reconstruction-guide.md) and consult the [data schema](./data-schema.md) for `waveorder`'s data format.
+**Reconstruct existing data:** start with the [reconstruction guide](guide/reconstruction-guide.md) and consult the [data schema](guide/data-schema.md) for `waveorder`'s data format.
 
-**Reconstruct with a GUI:** start with the [plugin's reconstruction guide](./napari-plugin-guide.md#reconstruction-tab).
+**Reconstruct with a GUI:** start with the [plugin's reconstruction guide](guide/napari-plugin-guide.md#acquisition--reconstruction-tab).
 
-**Integrate `waveorder` into my software:** start with [`examples/`](./examples/)
+
+**Integrate `waveorder` into my software:** start with [`examples/`](examples/)
 
 ## Hardware users
 
-**Buy hardware for a polarized-light installation:** start with the [buyer's guide](./buyers-guide.md).
+**Buy hardware for a polarized-light installation:** start with the [buyer's guide](guide/buyers-guide.md).
 
-**Install `waveorder` on my microscope:** start with the [microscope installation guide](./microscope-installation-guide.md).
+**Install `waveorder` on my microscope:** start with the [microscope installation guide](guide/microscope-installation-guide.md).
 
-**Use the `napari plugin` to calibrate:** start with the [plugin guide](./napari-plugin-guide.md).
+**Use the `napari plugin` to calibrate:** start with the [plugin guide](guide/napari-plugin-guide.md).
 
-**Understand `waveorder`'s calibration routine**: read the [calibration guide](./calibration-guide.md).
+**Understand `waveorder`'s calibration routine**: read the [calibration guide](guide/calibration-guide.md).
 
 ## Software developers
 
-**Set up a development environment and test `waveorder`**: start with the [development guide](./development-guide.md).
+**Set up a development environment and test `waveorder`**: start with the [development guide](guide/development-guide.md).
 
 **Report an error in the documentation or code:** [open an issue](https://github.com/mehta-lab/waveorder/issues/new/choose) or [send us an email](mailto:shalin.mehta@czbiohub.org,talon.chandler@czbiohub.org). We appreciate your help!
diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css
@@ -0,0 +1,8 @@
+blockquote {
+	background-color: var(--pst-color-background);
+	border-left: none;
+}
+
+video {
+    width: -webkit-fill-available;
+}
diff --git a/docs/images/HSV_legend.png → docs/_static/images/HSV_legend.png b/docs/images/HSV_legend.png → docs/_static/images/HSV_legend.png
diff --git a/docs/images/JCh_Color_legend.png → docs/_static/images/JCh_Color_legend.png b/docs/images/JCh_Color_legend.png → docs/_static/images/JCh_Color_legend.png
diff --git a/docs/images/JCh_legend.png → docs/_static/images/JCh_legend.png b/docs/images/JCh_legend.png → docs/_static/images/JCh_legend.png
diff --git a/docs/images/acq_finished.png → docs/_static/images/acq_finished.png b/docs/images/acq_finished.png → docs/_static/images/acq_finished.png
diff --git a/docs/images/acquire_buttons.png → docs/_static/images/acquire_buttons.png b/docs/images/acquire_buttons.png → docs/_static/images/acquire_buttons.png
diff --git a/docs/images/acquisition_settings.png → docs/_static/images/acquisition_settings.png b/docs/images/acquisition_settings.png → docs/_static/images/acquisition_settings.png
diff --git a/docs/images/advanced.png → docs/_static/images/advanced.png b/docs/images/advanced.png → docs/_static/images/advanced.png
diff --git a/docs/images/cap_bg.png → docs/_static/images/cap_bg.png b/docs/images/cap_bg.png → docs/_static/images/cap_bg.png
diff --git a/docs/images/cli_structure.png → docs/_static/images/cli_structure.png b/docs/images/cli_structure.png → docs/_static/images/cli_structure.png
diff --git a/docs/images/comms_video_screenshot.png → ..._static/images/comms_video_screenshot.png b/docs/images/comms_video_screenshot.png → ..._static/images/comms_video_screenshot.png
diff --git a/docs/images/connect_to_mm.png → docs/_static/images/connect_to_mm.png b/docs/images/connect_to_mm.png → docs/_static/images/connect_to_mm.png
diff --git a/docs/images/create_group.png → docs/_static/images/create_group.png b/docs/images/create_group.png → docs/_static/images/create_group.png
diff --git a/docs/images/create_group_voltage.png → docs/_static/images/create_group_voltage.png b/docs/images/create_group_voltage.png → docs/_static/images/create_group_voltage.png
diff --git a/docs/images/create_preset.png → docs/_static/images/create_preset.png b/docs/images/create_preset.png → docs/_static/images/create_preset.png
diff --git a/docs/images/create_preset_voltage.png → .../_static/images/create_preset_voltage.png b/docs/images/create_preset_voltage.png → .../_static/images/create_preset_voltage.png
diff --git a/...mages/general_reconstruction_settings.png → ...mages/general_reconstruction_settings.png b/...mages/general_reconstruction_settings.png → ...mages/general_reconstruction_settings.png
diff --git a/docs/images/ideal_plot.png → docs/_static/images/ideal_plot.png b/docs/images/ideal_plot.png → docs/_static/images/ideal_plot.png
diff --git a/docs/images/modulation.png → docs/_static/images/modulation.png b/docs/images/modulation.png → docs/_static/images/modulation.png
diff --git a/docs/images/no-overlay.png → docs/_static/images/no-overlay.png b/docs/images/no-overlay.png → docs/_static/images/no-overlay.png
diff --git a/docs/images/overlay-demo.png → docs/_static/images/overlay-demo.png b/docs/images/overlay-demo.png → docs/_static/images/overlay-demo.png
diff --git a/docs/images/overlay.png → docs/_static/images/overlay.png b/docs/images/overlay.png → docs/_static/images/overlay.png
diff --git a/.../images/phase_reconstruction_settings.png → .../images/phase_reconstruction_settings.png b/.../images/phase_reconstruction_settings.png → .../images/phase_reconstruction_settings.png
diff --git a/docs/images/poincare_swing.svg → docs/_static/images/poincare_swing.svg b/docs/images/poincare_swing.svg → docs/_static/images/poincare_swing.svg
diff --git a/.../images/reconstruction_birefriengence.png → .../images/reconstruction_birefriengence.png b/.../images/reconstruction_birefriengence.png → .../images/reconstruction_birefriengence.png
diff --git a/docs/images/reconstruction_data.png → docs/_static/images/reconstruction_data.png b/docs/images/reconstruction_data.png → docs/_static/images/reconstruction_data.png
diff --git a/docs/images/reconstruction_data_info.png → ...tatic/images/reconstruction_data_info.png b/docs/images/reconstruction_data_info.png → ...tatic/images/reconstruction_data_info.png
diff --git a/docs/images/reconstruction_models.png → .../_static/images/reconstruction_models.png b/docs/images/reconstruction_models.png → .../_static/images/reconstruction_models.png
diff --git a/docs/images/reconstruction_queue.png → docs/_static/images/reconstruction_queue.png b/docs/images/reconstruction_queue.png → docs/_static/images/reconstruction_queue.png
diff --git a/docs/images/run_calib.png → docs/_static/images/run_calib.png b/docs/images/run_calib.png → docs/_static/images/run_calib.png
diff --git a/docs/images/run_port.png → docs/_static/images/run_port.png b/docs/images/run_port.png → docs/_static/images/run_port.png
diff --git a/docs/images/waveorder_Fig1_Overview.png → ...static/images/waveorder_Fig1_Overview.png b/docs/images/waveorder_Fig1_Overview.png → ...static/images/waveorder_Fig1_Overview.png
diff --git a/docs/images/waveorder_plugin_logo.png → .../_static/images/waveorder_plugin_logo.png b/docs/images/waveorder_plugin_logo.png → .../_static/images/waveorder_plugin_logo.png
diff --git a/docs/_static/switcher.json b/docs/_static/switcher.json
@@ -0,0 +1,14 @@
+[
+    {
+        "version": "latest",
+        "url": "/en/latest/index.html"
+    },
+    {
+        "version": "v3.0.0a0",
+        "url": "/en/v3.0.0a0/index.html"
+    },
+    {
+        "version": "v2.2.1",
+        "url": "/en/v2.2.1/index.html"
+    }
+]
diff --git a/docs/_static/waveorder.ico b/docs/_static/waveorder.ico
diff --git a/docs/_static/waveorder.png b/docs/_static/waveorder.png
diff --git a/docs/api.rst b/docs/api.rst
@@ -0,0 +1,14 @@
+API Reference
+=============
+
+.. toctree::
+    :maxdepth: 3
+
+    api/settings
+    api/stokes
+
+Index
+-----
+
+* :ref:`genindex`
+* :ref:`search`
diff --git a/docs/api/settings.rst b/docs/api/settings.rst
@@ -0,0 +1,6 @@
+Settings
+========
+
+.. automodule:: waveorder.cli.settings
+    :members:
+    :undoc-members:
diff --git a/docs/api/stokes.rst b/docs/api/stokes.rst
@@ -0,0 +1,5 @@
+Stokes
+========
+
+.. automodule:: waveorder.stokes
+    :members: