Set up readthedocs

.gitignore

@@ -24,4 +24,7 @@ dist-ssr
 *.ntvs*
 *.njsproj
 *.sln
-*.sw?
+*.sw?
+# Sphinx docs
+.venv
+docs/_build

.prettierignore

@@ -1,4 +1,5 @@
 # Ignore artifacts:
 build
 coverage
-dist
+dist
+docs/_build

.readthedocs.yaml

@@ -0,0 +1,24 @@
+# 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.13"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.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:
+   - requirements: docs/requirements.txt
+
+

README.md

@@ -2,34 +2,16 @@
 
 This repo allows users to interact with lightcurves in the browser.
 
-## How to run dev server locally
+## Documentation
 
-Users can run this locally by following [the README in simonsobs/lightserve](https://github.com/simonsobs/lightserve) to run the server (requires Docker Desktop, as well).
+Please refer to the documentation at [lightview.readthedocs.io](https://lightview.readthedocs.io/en/latest/index.html) to learn how to run, configure, and release the application.
 
-Once the server is running locally, do the following:
+To build the docs locally:
 
-```js
-    git clone git@github.com:simonsobs/lightserve.git
-    cd lightserve
-    npm install
-    npm run dev
+```sh
+python -m venv .venv && source .venv/bin/activate
+pip install -r docs/requirements.txt
+make -C docs html
 ```
 
-## Tag and push a stable release
-
-The [build-and-push workflow](./.github/workflows/build-and-push.yml) builds and pushes the `latest` image on every push to `main`. Stable releases use version tags in the form `vMAJOR.MINOR.PATCH`, such as `v0.1.0`.
-
-First, make sure you are tagging the commit you want to release. Then create and push the tag:
-
-```bash
-git tag -a v0.1.0 -m "Release v0.1.0"
-git push origin v0.1.0
-```
-
-Pushing the tag triggers GitHub Actions to build and push a multi-platform image to GHCR. For the upstream repository, the image is published as:
-
-```text
-ghcr.io/simonsobs/lightview:v0.1.0
-```
-
-Check the repository's **Actions** tab to confirm that the build succeeded.
+Then open `docs/_build/html/index.html`.

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/custom.css

@@ -0,0 +1,9 @@
+h5 {
+  color: darkred;
+  font-weight: 900;
+}
+
+ul,
+ol {
+  margin-left: 1.25em;
+}

docs/conf.py

@@ -0,0 +1,39 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'LightView'
+copyright = '2025, Jeremy Myers, Josh Borrow'
+author = 'Jeremy Myers, Josh Borrow'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+# Add myst_parser so Sphinx can read Markdown
+extensions = [
+    "myst_parser",
+]
+
+myst_enable_extensions = [
+    "attrs_inline",   # enable inline {key=val} attributes for images/links/spans
+]
+
+# Tell Sphinx to treat .md files as source files
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'
+html_static_path = ['_static']
+html_css_files = ["custom.css"]

docs/configuration.md

@@ -0,0 +1,15 @@
+# Configuration
+
+`LightView` is configured with Vite environment variables. The dev server reads `.env.development` and production builds read `.env.production`; sample files for both are in the repository root.
+
+| Variable                  | Description                                      |
+| ------------------------- | ------------------------------------------------ |
+| `VITE_SERVICE_URL`        | URL of the lightserve backend                    |
+| `VITE_AUTH_ENABLED`       | Enables login/logout                             |
+| `VITE_LOGIN_SERVICE`      | Login service URL                                |
+| `VITE_LOGOUT_SERVICE`     | Logout service URL                               |
+| `VITE_CROSSMATCH_ENABLED` | Shows the crossmatch button                      |
+| `VITE_ORGANIZATION_NAME`  | Organization name shown in the navbar (optional) |
+| `VITE_APP_NAME`           | App name shown in the navbar                     |
+| `VITE_APP_TITLE`          | Title shown in the browser tab                   |
+| `VITE_CONTACT_EMAIL`      | Contact email shown in the footer                |

docs/getting-started.md

@@ -0,0 +1,29 @@
+# Getting Started
+
+## Run the dev server locally
+
+`LightView` reads its data from a [lightserve](https://github.com/simonsobs/lightserve) instance. Follow [the lightserve README](https://github.com/simonsobs/lightserve#readme) to run the server locally (this requires Docker Desktop).
+
+Once the server is running:
+
+1. Clone and initialize `LightView`
+
+```sh
+git clone git@github.com:simonsobs/lightview.git
+cd lightview
+npm install
+```
+
+2. Create a `.env.development` file by copying the contents from `.env.development.sample`. You may need to amend `VITE_SERVICE_URL` depending on what port your lightserve instance runs on. See [Configuration](configuration.md) for all available options.
+
+3. Start the dev server
+
+```sh
+npm run dev
+```
+
+## Run the tests
+
+```sh
+npm run test:run
+```

docs/index.md

@@ -0,0 +1,13 @@
+# Welcome to LightView
+
+LightView is the Simons Observatory Light Curve Viewer: a web application for browsing and interacting with astronomical light curves in the browser. It is a client for the [lightserve](https://github.com/simonsobs/lightserve) API.
+
+```{toctree}
+   :maxdepth: 3
+   :hidden:
+
+getting-started.md
+configuration.md
+releases.md
+
+```

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/releases.md

@@ -0,0 +1,20 @@
+# Releases
+
+The [build-and-push workflow](https://github.com/simonsobs/lightview/blob/main/.github/workflows/build-and-push.yml) builds and pushes the `latest` image on every push to `main`. Stable releases use version tags in the form `vMAJOR.MINOR.PATCH`, such as `v0.1.0`.
+
+## Tag and push a stable release
+
+First, make sure you are tagging the commit you want to release. Then create and push the tag:
+
+```bash
+git tag -a v0.1.0 -m "Release v0.1.0"
+git push origin v0.1.0
+```
+
+Pushing the tag triggers GitHub Actions to build and push a multi-platform image to GHCR. For the upstream repository, the image is published as:
+
+```text
+ghcr.io/simonsobs/lightview:v0.1.0
+```
+
+Check the repository's **Actions** tab to confirm that the build succeeded.

docs/requirements.txt

@@ -0,0 +1,2 @@
+sphinx
+myst-parser