Skip to content

Migrate from conda to pixi and from Sphinx to MkDocs - #293

Open
euronion wants to merge 4 commits into
masterfrom
pixi-mkdocs
Open

euronion wants to merge 4 commits into
masterfrom
pixi-mkdocs

Conversation

@euronion

@euronion euronion commented Nov 6, 2026 •

Copy link
Copy Markdown
Collaborator

Note

This PR description and the changes were created with the help of AI (Claude Code) and reviewed by the author.

Changes proposed in this Pull Request

This PR moves

  1. environment management from conda to pixi
  2. the documentation from Sphinx/RST to MkDocs/Material.

Both follow the setup in PyPSA-Eur.

1. conda --> pixi

  • pixi.toml and pixi.lock. Also addresses the CI failure in e.g. Fix bug preventing add_energy_storage_database to run through #286 which is caused by non-pinned packages / package version misalignment.
  • tabula-py and currencyconverter now come from conda-forge, so no pip dependencies anymore.
  • Missing deps (implicit) added
  • Raise the Python minimum is now 3.12.
  • New pixi tasks: pixi run unit-tests, pixi run run-all (full workflow), pixi run build-docs <dir> and pixi run sync-locks. CI runs the two test workflows with pixi run -e test snakemake ... directly.
  • pixi run sync-locks exports envs/environment.yaml and envs/default_<platform>.pin.txt, so conda users still have a supported path. Like in PyPSA-Eur. The root environment.yaml is removed.
  • conda: directives are removed from the Snakefile. Instead run pixi run snakemake ...
  • New update-lockfile.yaml workflow. It opens a PR with refreshed locks twice a month.

2. Sphinx --> MkDocs

  • New mkdocs.yml with the Material theme. mkdocs is pinned to <2 for known reasons.
  • CSV tables use {{ read_csv(...) }}. Code excerpts use pymdownx.snippets sections. The markers in scripts/compile_cost_assumptions.py changed from # [name] to # --8<-- [start:name] / # --8<-- [end:name].

Side-fix:

  • The add-solar-from-others excerpt in addnew rendered empty before, because its marker did not exist. It now has a marker.

Important breaking changes

  • environment.yaml moved to envs/environment.yaml and holds only runtime dependencies.
  • Python ≥ 3.12 is required.
  • The URLs of doc sub-pages change from /installation.html to /installation/.

Questions for @lkstrp

  • update-lockfile.yaml needs the repo setting "Allow GitHub Actions to create and approve pull requests" - can you configure?
  • Do we need to change anything in RTDs, or is it sufficient to change the config files in the repo?

Checklist

  • Code changes are sufficiently documented; i.e. new functions contain docstrings and further explanations may be given in doc.
  • [n/a] Data source for new technologies is clearly stated. (not applicable)
  • Newly introduced dependencies are added to pixi.toml and pixi run sync-locks was run (if applicable).
  • A note for the release notes doc/release_notes.md of the upcoming release is included.
  • I consent to the release of this PR's code under the GPLv3 license.

Add pixi.toml/pixi.lock (default, dev, test, doc envs) and sync-locks task exporting conda files to envs/.
Replace Makefile with pixi tasks, micromamba CI with setup-pixi, add bi-weekly lockfile update workflow.
Build RTD docs via pixi; drop conda directives from Snakefile; update docs and templates.
Pure renames to preserve history; content is converted in the next commit.
Convert doc/*.md pages, add mkdocs.yml (search, table-reader, snippets) and PyPSA-Eur colour css.
Replace literalinclude markers in compile_cost_assumptions.py with snippet sections; fix missing add-solar-from-others.
Build RTD with mkdocs via pixi doc env; drop doc/conf.py and doc/Makefile.
@euronion
euronion force-pushed the pixi-mkdocs branch 2 times, most recently from f54c703 to 9c46f8e Compare November 6, 2026 13:32
@euronion
euronion marked this pull request as ready for review November 6, 2026 13:44
@euronion
euronion requested a review from lkstrp November 6, 2026 13:44
@euronion

euronion commented Nov 6, 2026

Copy link
Copy Markdown
Collaborator Author

Hi @lkstrp , can you please review?
@fneum FYI, finally aligning the repo tools here with PyPSA-Eur

@fneum

fneum commented Nov 6, 2026

Copy link
Copy Markdown
Member

Totally fine with this PR! Thanks for taking care of it!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants