diff --git a/.gitignore b/.gitignore index cd3a070..494c0b3 100644 --- a/.gitignore +++ b/.gitignore @@ -24,4 +24,7 @@ dist-ssr *.ntvs* *.njsproj *.sln -*.sw? \ No newline at end of file +*.sw? +# Sphinx docs +.venv +docs/_build diff --git a/.prettierignore b/.prettierignore index ab53970..d25ab85 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,4 +1,5 @@ # Ignore artifacts: build coverage -dist \ No newline at end of file +dist +docs/_build diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..3dc302b --- /dev/null +++ b/.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 + + diff --git a/README.md b/README.md index 89a397e..36c4a02 100644 --- a/README.md +++ b/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`. diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/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) diff --git a/docs/_static/custom.css b/docs/_static/custom.css new file mode 100644 index 0000000..a98fdee --- /dev/null +++ b/docs/_static/custom.css @@ -0,0 +1,9 @@ +h5 { + color: darkred; + font-weight: 900; +} + +ul, +ol { + margin-left: 1.25em; +} diff --git a/docs/_templates/.gitkeep b/docs/_templates/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..b6bd0a8 --- /dev/null +++ b/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"] diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..f727e0f --- /dev/null +++ b/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 | diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..f0cc5e0 --- /dev/null +++ b/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 +``` diff --git a/docs/images/.gitkeep b/docs/images/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..121c9c8 --- /dev/null +++ b/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 + +``` diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..32bb245 --- /dev/null +++ b/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 diff --git a/docs/releases.md b/docs/releases.md new file mode 100644 index 0000000..cc45130 --- /dev/null +++ b/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. diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..98a3c62 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +sphinx +myst-parser