Reusable code for component efficiencies

.github/workflows/deploy_docs.yaml

@@ -58,10 +58,7 @@ jobs:
         # base path to build correct links to its static assets.
         env:
           BASE_URL: "/${{ github.event.repository.name }}"
-        # TODO: consider adding --strict once a strict + execute build is
-        # confirmed clean, so broken links/refs and execution errors fail the
-        # deploy instead of silently publishing.
-        run: jupyter book build --html --execute
+        run: jupyter book build --strict --html --execute
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3

docs/content/developers/compiling-from-source.md

@@ -0,0 +1,13 @@
+# Compiling from Source
+
+First, set up your environment (see [Environment Setup](environment-setup.md)).
+
+To compile FASTSim from source and install into your environment, run:
+```bash
+maturin develop
+```
+
+Or, to compile with optimizations (longer compilation, but faster at runtime):
+```bash
+maturin develop --release
+```

docs/content/developers/environment-setup.md

@@ -0,0 +1,130 @@
+# Environment Setup
+
+A few options exist for environment setup:
+1. [Pixi (recommended)](#1-pixi)
+2. [Anaconda](#2-anaconda)
+2. [Custom](#3-custom)
+
+(1-pixi)=
+## 1. Pixi
+[Pixi](https://pixi.prefix.dev/latest/) is a tool that ensures environment hygiene and reproducibility. FASTSim has an established setup for 
+Pixi that you can take advantage of to quickly get started.
+
+### Pixi Installation
+
+Full installation instructions are available in the pixi docs:
+[https://pixi.prefix.dev/latest/installation/](https://pixi.prefix.dev/latest/installation/)
+
+After installation, confirm pixi is available in a fresh terminal:
+
+```sh
+pixi --version
+```
+
+### Environment Installation
+
+From the repository root, install FASTSim and development dependencies:
+
+```sh
+pixi install -e dev
+```
+
+The `dev` Pixi environment installs FASTSim, the Rust compiler, testing dependencies, and other conveniences. If these are not necessary, see the `pyproject.toml` file for other options.
+
+### Environment Usage
+
+To use the environment in a terminal:
+
+- Run individual commands:
+
+```sh
+pixi run -e dev <command>
+```
+
+- Or, activate an interactive shell:
+
+```sh
+pixi shell -e dev
+```
+
+See the Pixi documentation or run `pixi --help` for more usage information. The [direnv](https://direnv.net) tool automates launching a shell for you, and FASTSim has a preconfigured `.envrc` file. 
+
+### direnv: Automatic Environment Activation
+
+If you use direnv, you can auto-load the pixi dev environment when entering this repository.
+
+Setup:
+
+1. Install direnv: [https://direnv.net/docs/installation.html](https://direnv.net/docs/installation.html)
+2. Enable the hook for your shell (see [direnv docs](https://direnv.net/docs/hook.html)).
+3. Allow `direnv` to run `.envrc`:
+    ```sh
+    direnv allow
+    ```
+
+After that, entering the directory will auto-activate the pixi `dev` environment. Messages about environment variables can be suppressed by creating `~/.config/direnv/direnv.toml` containing the line:
+```toml
+hide_env_diff = true
+```
+
+(2-anaconda)=
+## 2. Anaconda
+
+Anaconda users can easily install Rust using the conda-forge `rust` package
+
+1. Create a new environment with Python and Rust (e.g. named `fastsim`)
+    ```
+    conda create --name fastsim python=3.12 rust -c conda-forge
+    ```
+
+2. Activate the new environment
+    ```
+    conda activate fastsim
+    ```
+
+2. From the repository root, install FASTSim and development dependencies:
+
+    ```sh
+    pip install --upgrade pip
+    pip install --group dev -e .
+    ```
+
+:::{note}
+This section suggests dependencies independent of the `pyproject.toml`, so may become outdated.
+
+As of writing, a way to build an Anaconda environment from `pixi.lock` using
+the [`conda-lockfiles` plugin](https://github.com/conda/conda-lockfiles) is nearly supported:
+
+```console
+conda install --name base conda-forge::conda-lockfiles
+```
+
+```
+conda env create --name fastsim --file pixi.lock
+```
+
+However, this plugin only supports `pixi.lock` version 6, while version 7 released in [May 2026](https://pixi.prefix.dev/latest/CHANGELOG/#0680-2026-05-07).
+
+Output:
+```
+PluginError: Failed to parse environment specification from file: field 'version': Input should be less than or equal to 6
+```
+
+Relevant links:
+- https://github.com/conda/conda-lockfiles/pull/143
+- https://github.com/conda/conda-lockfiles/issues/44
+:::
+
+
+(3-custom)=
+## 3. Custom
+
+If you do not want to use Pixi or Anaconda, install Rust and Python dependencies manually.
+
+1. Install Rust system-wide: [https://www.rust-lang.org/tools/install](https://www.rust-lang.org/tools/install)
+2. Create and activate a Python environment (using your environment manager of choice).
+3. From the repository root, install FASTSim and development dependencies:
+
+    ```sh
+    pip install --group dev -e .
+    ```

docs/content/developers/making-releases.md

@@ -0,0 +1,31 @@
+# Making Releases
+
+1. Determine new version number according to [semantic versioning conventions](https://semver.org/)
+
+1. Update FASTSim version in the following locations:
+    - `pyproject.toml`
+    - `fastsim-core/Cargo.toml`
+      - package version
+      - `fastsim-proc-macros` dependency version
+    - `fastsim-core/fastsim-proc-macros/Cargo.toml`
+    - `fastsim-py/Cargo.toml`
+
+    Commit these changes via git
+
+1. Tag the latest commit with your version number and push
+
+    ```
+    git tag vX.Y.Z
+    ```
+
+    ```
+    git push origin tag vX.Y.Z
+    ```
+
+1. Draft a new release at https://github.com/NatLabRockies/fastsim/releases/new
+    - Select the newly created tag
+    - Autogenerate release notes
+    - Add extra description of changes, new features, bugfixes, etc.
+
+1. Publish release
+    - GitHub Actions will take care of testing, building wheels, and releasing to [PyPI](https://pypi.org/project/fastsim/) and [crates.io](https://crates.io/crates/fastsim-core)

docs/content/developers/updating-docs.md

@@ -0,0 +1,77 @@
+# Updating the Docs
+
+This documentation is built using [Jupyter Book v2](https://mystmd.org/) (MyST).
+
+
+
+## Setup
+
+Install the doc build dependencies:
+
+- Using Pixi:
+  ```bash
+  pixi install -e docs
+  ```
+
+- Manually:
+  ```bash
+  pip install --group docs
+  ```
+
+## Local Development
+
+Convert the demo scripts to notebooks and launch the jupyter book, executing notebooks
+
+- Using Pixi:
+  ```bash
+  pixi run docs
+  ```
+
+- Manually:
+  1. Change to the `docs/` directory
+
+      ```bash
+      cd docs
+      ```
+  1. Start the dev server with live reload:
+
+      ```bash
+      jupyter book start --execute
+      ```
+
+      The `--execute` flag runs the demo notebooks and populates their outputs,
+      allowing plots to appear in the rendered pages
+
+The site will be available at `http://localhost:3000`
+
+## Building Static HTML
+
+```bash
+jupyter book build --strict --html --execute
+```
+
+Output is written to `docs/_build/html/`. The `--strict` flag checks for broken internal references.
+
+## Directory Layout
+
+```
+docs/
+  content/            Markdown pages and notebooks
+  assets/             Images and icons
+  myst.yml            Jupyter Book configuration and table of contents
+```
+
+## Adding or Modifying Pages
+
+1. Add `.md` and/or `.ipynb` files to `docs/content/`
+
+1. Edit the table of contents `docs/myst.yml` to reflect the updated directory structure
+
+1. Check that a 'strict' build of the docs runs cleanly
+
+    `jupyter book build --strict --html --execute`
+
+## Publishing
+
+Pushing to the `fastsim-3` branch triggers a GitHub Actions workflow
+(`deploy_docs.yaml`) that builds and deploys the book to GitHub Pages.