From 3d0e496d8a6b2e8df7e54dd5d666f6ba7596186c Mon Sep 17 00:00:00 2001
From: Daniel Himmelstein <daniel.himmelstein@gmail.com>
Date: Wed, 25 Dec 2024 11:48:57 -0500
Subject: [PATCH] readme: refine installation and dev docs

follow up to https://github.com/dhimmel/openskistats/pull/25
---
 README.md                | 113 +++++++++++++++++++++++++--------------
 openskistats/commands.py |   4 +-
 2 files changed, 77 insertions(+), 40 deletions(-)

diff --git a/README.md b/README.md
index e9fc5c1fdf..6f5e8a7df1 100644
--- a/README.md
+++ b/README.md
@@ -12,65 +12,100 @@ The first application is the creation of roses showing the compass orientations
 
 ## Development
 
+The [`analyze` workflow](.github/workflows/analyze.yaml) performs a complete installation of dependencies on Linux and runs the analysis.
+It serves as the reference for installing dependencies and executing the analysis, as well as the sole deployment route.
+For convenience, we provide some local development instructions below.
+
+### Installation
+
+Installation and execution requires several system dependencies,
+whose installation and presence varies by platform.
+The following commands are one method of installation on macOS:
+
 ```shell
-# download latest OpenSkiMap data
-uv run openskistats download
+brew install imagemagick@6
 
-# extract ski area metadata and metrics
-uv run openskistats analyze
+# install the fallback font if you don't have it
+# otherwise uv run openskistats visualize will warn:
+# WARNING:matplotlib.font_manager:findfont: Font family 'Noto Sans CJK JP' not found.
+brew install --cask font-noto-sans-cjk
+```
+
+For initial Python setup, first [install uv](https://docs.astral.sh/uv/getting-started/installation/).
+Then run the following commands:
+
+```shell
+# install the uv environment in uv.lock
+uv sync --extra=dev
 
-uv run openskistats visualize
-uv run openskistats display
+# install the pre-commit git hooks
+pre-commit install
+```
 
-# story dependencies (must install R and renv first)
-# If R is not already installed, use Homebrew to install it:
-brew install r
+[Install quarto](https://quarto.org/docs/get-started/) and extensions:
 
-# 2. Verify R Installation
+```shell
+# install quarto story extension
+(cd website/story && quarto add --no-prompt https://github.com/qmd-lab/closeread/archive/e3645070dd668004056ae508d2d25d05baca5ad1.zip)
+```
+
+Install [R](https://cran.r-project.org/) and the `renv` environment:
+
+```shell
 # Check that R is installed by running:
 R --version
 
-# Installing Dependencies
+# Install the R environment by restoring the project's dependencies in the `renv.lock` file:
+Rscript -e "setwd('r'); renv::restore()"
+```
 
-# 1. Install the `renv` Package
-# Open an R console:
-R
+### Execution
 
-# In the R session, install `renv`:
-brew install imagemagick@6
-install.packages("renv")
+For commands that require access to the python environment,
+which includes those beginning with `openskistats` and `quarto`,
+you can activate the `uv` environment any of the following ways:
 
-# Exit the R session:
-quit()
+- configure your IDE to activate the venv automatically, e.g. via "Python: Select Interpreter" [in](https://code.visualstudio.com/docs/python/environments) Visual Studio Code.
+- prefix the command with `uv run`, e.g. `uv run openskistats --help`
+- [activate](https://docs.astral.sh/uv/pip/environments/#using-a-virtual-environment) the venv like `source .venv/bin/activate`
 
-# 2. Restore Dependencies with `renv`
-# Use the following command to restore the project's dependencies as defined in the `renv.lock` file:
-Rscript -e "setwd('r'); renv::restore()"
+To execute the Python analysis, run the following commands:
 
-brew install quarto
-# install story extension
-(cd website/story && quarto add --no-prompt https://github.com/qmd-lab/closeread/archive/e3645070dd668004056ae508d2d25d05baca5ad1.zip)
-source .venv/bin/activate
-quarto render website
-quarto preview website
+```shell
+# download latest OpenSkiMap data
+# run infrequently as we want to minimize stress on the OpenSkiMap servers
+# downloads persist locally
+openskistats download
 
-# webserver for viewing http://localhost:8000
-python -m http.server --directory=data/webapp
+# extract ski area metadata and metrics
+openskistats analyze
+
+openskistats visualize
+
+# run python test suite
+pytest
+
+# run the full pre-commit suite
+pre-commit run --all
 ```
 
-Commands that you will have to run less frequently:
+To execute the R analysis, run the following command:
 
 ```shell
-# install the uv environment in uv.lock
-uv sync --extra=dev
+cd r
+Rscript 01.data.R
+Rscript 02.plot.R
+```
 
-# install the pre-commit git hooks
-pre-commit install
+To render the website, use either:
 
-# install the fallback font if you don't have it
-# otherwise uv run openskistats analyze will give error:
-# WARNING:matplotlib.font_manager:findfont: Font family 'Noto Sans CJK JP' not found.
-brew install --cask font-noto-sans-cjk
+```shell
+# using quarto preview to render and serve
+quarto preview website
+
+# render and serve to <http://localhost:8000> manually 
+quarto render website
+python -m http.server --directory=data/webapp
 ```
 
 ## References
diff --git a/openskistats/commands.py b/openskistats/commands.py
index e3dd6e476d..fa69fcdc4a 100644
--- a/openskistats/commands.py
+++ b/openskistats/commands.py
@@ -52,10 +52,12 @@ def visualize(
         create_ski_area_roses(overwrite=overwrite)
 
     @staticmethod
-    @cli.command(name="display")  # type: ignore [misc]
+    @cli.command(name="display", deprecated=True)  # type: ignore [misc]
     def display() -> None:
         """
         Display ski area metrics in a web browser.
+        DEPRECATED: table is rendered in quarto website.
+        This command should be removed in the future.
         """
         export_display_notebook()