Docs/readme and modules - #58
Open
JanTautorus wants to merge 2 commits into
Open
Conversation
energyLS
requested changes
Aug 13, 2026
Uh oh!
There was an error while loading. Please reload this page.
Adds a proper docs/ site built with mkdocs + mkdocs-material +
mkdocstrings-python (new `docs` pixi feature/environment: `pixi run -e
docs mkdocs serve`), covering:
- installation.md: pixi setup, the two supported solvers (gurobi/highs)
and how config.yaml/env vars select between them, and the Windows
Snakemake scheduler workaround (--scheduler greedy).
- workflow.md: the three pipeline stages, plus a new section on the
enable.{cluster_renewables,run_supply_chain,run_supply_curve} flags -
each one conditionally defines an entire rule in the .smk files rather
than just gating a re-run, so they need to be True on a first run
against a given config and can be set False afterward, but only stay
correct as long as nothing the cached resources depend on (regions,
cost_year, ...) has changed since.
- modules.md: auto-generated reference for every workflow/scripts/*.py,
pulled live from each module's docstring via mkdocstrings so it can't
drift out of sync the way hand-written API docs would.
Also fills in the module docstring for the 3 scripts that had none
(_helpers.py, create_supply_curve.py, model_trade.py), and fixes two
existing docstrings (download_labour_data.py, preprocess_consolidate_
renewables.py) whose plain-text `[--flag]` usage examples were being
misparsed as broken markdown cross-reference links by mkdocs-autorefs -
verified with `mkdocs build --strict` (zero warnings) after the fix.
README.md is trimmed to a short overview + quick start + pointer to the
docs site, since the workflow-stage and setup detail it used to carry
duplicates what's now in docs/ (and was prone to drifting out of sync,
same as the module docs before mkdocstrings).
While checking what README's `collect_figures` mention actually does:
confirmed via `snakemake -n collect_figures` that it does not currently
work - the rule's input: block references wildcards (wacc, scenario,
sort, demand) never bound to concrete values anywhere, so Snakemake
fails with a WildcardError before it can even build the DAG. Left as
documented-broken rather than silently implying it works.JanTautorusforce-pushed
the
docs/readme-and-modules
branch
from
August 13, 2026 16:38
8b0f7c5 to
a1afac8Comparepixi run already activates the environment per-invocation, so the
pixi shell step in the README was redundant; drop it and split the
section into install + a short "key results" pointer.
resources/ is gitignored, so a fresh clone had nothing on disk for
the enable.{run_supply_chain,run_supply_curve,cluster_renewables}
gated rules to consume - the documented quick start command failed
out of the box with enable defaulting to False. Default all three to
True so it actually runs end-to-end, and update workflow.md to match.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
trim readme and add minimal docs for installation, workflow and config