From 21303f96144663c3491dea8e1f0aea4e013cf9e4 Mon Sep 17 00:00:00 2001 From: Alex Dewar Date: Fri, 9 Jan 2026 08:15:40 +0000 Subject: [PATCH 1/6] Include link to API docs in TOC --- docs/SUMMARY.md | 1 + docs/api/muse2/.gitkeep | 0 docs/api/muse2/README.md | 9 +++++++++ 3 files changed, 10 insertions(+) delete mode 100644 docs/api/muse2/.gitkeep create mode 100644 docs/api/muse2/README.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 5a1d47bf9..0a8dbfb46 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -15,3 +15,4 @@ - [Model Diagrams](model/model_diagrams.md) - [Glossary](glossary.md) - [Developer Guide](developer_guide.md) +- [API documentation](./api/muse2/README.md) diff --git a/docs/api/muse2/.gitkeep b/docs/api/muse2/.gitkeep deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/api/muse2/README.md b/docs/api/muse2/README.md new file mode 100644 index 000000000..04a8c8c5f --- /dev/null +++ b/docs/api/muse2/README.md @@ -0,0 +1,9 @@ +# API documentation + +This is a placeholder file for the MUSE2 API documentation. This content will be replaced with the +output of [`rustdoc`] when run by GitHub Actions. + +To view the latest version of the API documentation online, [see +here](https://energysystemsmodellinglab.github.io/MUSE2/api/muse2/). + +[`rustdoc`]: https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html From 176c6f03bbcf4ba28ed2a6d3d6401849b1d5e2c4 Mon Sep 17 00:00:00 2001 From: Alex Dewar Date: Fri, 9 Jan 2026 11:59:44 +0000 Subject: [PATCH 2/6] Rename main docs files in subfolders to `README.md` mdBook automatically converts these to `index.html`. By doing it this way, the main file will be displayed if manually navigating through the repo on GitHub. --- docs/{introduction.md => README.md} | 2 +- docs/SUMMARY.md | 6 +++--- docs/file_formats/{file_formats.md => README.md} | 0 docs/model/{model_description.md => README.md} | 0 docs/model/investment.md | 4 ++-- 5 files changed, 6 insertions(+), 6 deletions(-) rename docs/{introduction.md => README.md} (93%) rename docs/file_formats/{file_formats.md => README.md} (100%) rename docs/model/{model_description.md => README.md} (100%) diff --git a/docs/introduction.md b/docs/README.md similarity index 93% rename from docs/introduction.md rename to docs/README.md index ce366dbab..ffbc3a1ab 100644 --- a/docs/introduction.md +++ b/docs/README.md @@ -12,7 +12,7 @@ If you are a developer, please see the [developer guide]. [the older MUSE tool]: https://github.com/EnergySystemsModellingLab/MUSE_OS [user guide]: ./user_guide.md [command line help]: ./command_line_help.md -[model description]: ./model/model_description.md +[model description]: ./model/ [dispatch optimisation formulation]: ./model/dispatch_optimisation.md [glossary]: ./glossary.md [developer guide]: ./developer_guide.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 0a8dbfb46..b63308a73 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -1,15 +1,15 @@ # Summary -[Introduction](introduction.md) +[Introduction](README.md) - [User Guide](user_guide.md) - [Example Models](examples.md) - [Command Line Help](command_line_help.md) -- [File Formats](file_formats/file_formats.md) +- [File Formats](file_formats/README.md) - [Program Settings](file_formats/program_settings.md) - [Input Files](file_formats/input_files.md) - [Output Files](file_formats/output_files.md) -- [Model Description](model/model_description.md) +- [Model Description](model/README.md) - [Dispatch Optimisation](model/dispatch_optimisation.md) - [Investment Appraisal](model/investment.md) - [Model Diagrams](model/model_diagrams.md) diff --git a/docs/file_formats/file_formats.md b/docs/file_formats/README.md similarity index 100% rename from docs/file_formats/file_formats.md rename to docs/file_formats/README.md diff --git a/docs/model/model_description.md b/docs/model/README.md similarity index 100% rename from docs/model/model_description.md rename to docs/model/README.md diff --git a/docs/model/investment.md b/docs/model/investment.md index 134d90710..8d9c39105 100644 --- a/docs/model/investment.md +++ b/docs/model/investment.md @@ -203,6 +203,6 @@ For each asset option: AFC \* cap_r + \sum_{t} act_t \* AC_t \\)), divided by the annual output \\( \sum_t act_t \\). -[overall MUSE2 workflow]: ./model_description.md#framework-overview +[overall MUSE2 workflow]: ./README.md#framework-overview [Dispatch Optimisation Formulation]: ./dispatch_optimisation.md -[ironing-out loop]: ./model_description.md#framework-overview +[ironing-out loop]: ./README.md#framework-overview From 0f0a4cf6024981658b4ccf32e4830a8e894cff3b Mon Sep 17 00:00:00 2001 From: Alex Dewar Date: Fri, 9 Jan 2026 12:03:57 +0000 Subject: [PATCH 3/6] Replace unicode apostrophes --- CITATION.cff | 2 +- docs/model/dispatch_optimisation.md | 4 ++-- docs/model/investment.md | 12 ++++++------ 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/CITATION.cff b/CITATION.cff index ff39cfc28..f98c615f8 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -4,7 +4,7 @@ message: | This work was supported via the Climate Compatible Growth (CCG) programme and the EPSRC-funded HI-ACT project (EP/X038823/2). CCG is funded by UK Aid from the UK government. However, the views - expressed herein do not necessarily reflect the UK government’s official policies. + expressed herein do not necessarily reflect the UK government's official policies. title: MUSE2 version: 2.0.0 date-released: 2025-10-14 diff --git a/docs/model/dispatch_optimisation.md b/docs/model/dispatch_optimisation.md index 461277cd4..cedc064dc 100644 --- a/docs/model/dispatch_optimisation.md +++ b/docs/model/dispatch_optimisation.md @@ -61,7 +61,7 @@ These define the fundamental categories used to define the energy system. - \\( season\\_ slice[h,t] \\): Binary indicator; \\( 1 \\) if time slice \\( t \\) is in season \\( h \\), \\( 0 \\) otherwise. Facilitates seasonal aggregation. -- \\( balance\\_ level[c,r] \\): Defines the temporal resolution (’timeslice’, ’seasonal’, ’annual’) +- \\( balance\\_ level[c,r] \\): Defines the temporal resolution ('timeslice', 'seasonal', 'annual') at which the supply-demand balance for commodity \\( c \\) in region \\( r \\) must be enforced. - \\( demand[r,c] \\): Total annual exogenously specified demand (\\( \ge 0 \\)) for commodity \\( c @@ -131,7 +131,7 @@ component of the overall system cost that the model seeks to minimise. ### A.4. Constraints (Capacity & Availability for standard assets \\( a \in \mathbf{A}^{std} \\)) -These constraints ensure that each standard asset’s operation respects its physical capacity and +These constraints ensure that each standard asset's operation respects its physical capacity and time-varying availability limits. For all \\( a \in \mathbf{A}^{std}, r, t \\): - Asset activity \\( act[a,r,t] \\) is constrained by its available capacity, considering its diff --git a/docs/model/investment.md b/docs/model/investment.md index 8d9c39105..2ee29bbaf 100644 --- a/docs/model/investment.md +++ b/docs/model/investment.md @@ -131,14 +131,14 @@ providing investment and dynamic decommissioning decisions. #### Tool A: NPV This method is used when decision rule is single objective and objective is annualised profit for -agents’ serving commodity \\( c \\). This method iteratively builds a supply portfolio by selecting +agents' serving commodity \\( c \\). This method iteratively builds a supply portfolio by selecting options that offer the highest annualised profit for serving the current commodity demand. The economic evaluation uses \\( \pi_{prevMSY} \\) prices and takes account of asset-specific operational constraints (e.g., minimum load levels) and the balance level of the target commodity (time slice profile, seasonal or annual). For each asset option: - **Optimise capacity and dispatch to maximise annualised profit:** Solve a small optimisation - sub-problem to maximise the asset’s surplus, subject to its operational rules and the specific + sub-problem to maximise the asset's surplus, subject to its operational rules and the specific demand tranche it is being asked to serve. \\(\varepsilon \approx 1×10^{-14}\\) is added to each \\(AC_t \\) to allow assets which are breakeven (or very close to breakeven) to be dispatched. @@ -153,7 +153,7 @@ operational constraints (e.g., minimum load levels) and the balance level of the than capacity, applied to its activity profile \\( act_t \\). - A demand constraint, where output cannot exceed demand in the tranche, which adapts based on the - commodity’s balance level (time slice, season, annual). + commodity's balance level (time slice, season, annual). - Capacity is constrained to \\( CapMaxBuild \\) for candidates, and to known capacity for existing assets. @@ -164,7 +164,7 @@ operational constraints (e.g., minimum load levels) and the balance level of the #### Tool B: LCOX -This method is used when decision rule is single objective and objective is LCOX for agents’ serving +This method is used when decision rule is single objective and objective is LCOX for agents' serving commodity \\( c \\). This method constructs a supply portfolio (from new candidates \\( ca \\), new import infrastructure \\( ca_{import} \\), and available existing assets \\( ex \\)) to meet target \\( U_{c} \\) at the lowest cost for the investor. As above, the appraisal for each option @@ -175,7 +175,7 @@ commodities are set to zero, and the commodity of interest is assumed to have ze For each asset option: - **Optimise capacity and dispatch to minimise annualised cost:** Solve a small optimisation - sub-problem to maximise the asset’s surplus, subject to its operational rules and the specific + sub-problem to maximise the asset's surplus, subject to its operational rules and the specific demand tranche it is being asked to serve. \\[ @@ -190,7 +190,7 @@ For each asset option: than capacity, applied to its activity profile \\( act_t \\). - A demand constraint, where output from the asset plus VoLL-related outputs must equal demand in - each timeslice of the tranche, which adapts based on the commodity’s balance level (time slice, + each timeslice of the tranche, which adapts based on the commodity's balance level (time slice, season, annual). - Capacity is constrained to \\( CapMaxBuild \\) for candidates, and to known capacity for From 715b329954aad88d597d8fd175e8b499005eb270 Mon Sep 17 00:00:00 2001 From: Alex Dewar Date: Fri, 9 Jan 2026 12:13:32 +0000 Subject: [PATCH 4/6] Split developer docs into separate chapters --- CONTRIBUTING.md | 2 +- docs/README.md | 2 +- docs/SUMMARY.md | 5 +- docs/developer_guide.md | 280 --------------------------------- docs/developer_guide/README.md | 6 + docs/developer_guide/coding.md | 76 +++++++++ docs/developer_guide/docs.md | 86 ++++++++++ docs/developer_guide/setup.md | 117 ++++++++++++++ 8 files changed, 291 insertions(+), 283 deletions(-) delete mode 100644 docs/developer_guide.md create mode 100644 docs/developer_guide/README.md create mode 100644 docs/developer_guide/coding.md create mode 100644 docs/developer_guide/docs.md create mode 100644 docs/developer_guide/setup.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 12e5961e6..59c2b7432 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -190,4 +190,4 @@ on how to write the documentation. ## Developer Setup -Please see the [developer guide](docs/developer_guide.md). +Please see the [developer guide](docs/developer_guide/). diff --git a/docs/README.md b/docs/README.md index ffbc3a1ab..4ed7b6a09 100644 --- a/docs/README.md +++ b/docs/README.md @@ -15,4 +15,4 @@ If you are a developer, please see the [developer guide]. [model description]: ./model/ [dispatch optimisation formulation]: ./model/dispatch_optimisation.md [glossary]: ./glossary.md -[developer guide]: ./developer_guide.md +[developer guide]: ./developer_guide/ diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index b63308a73..4c6b5a705 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -14,5 +14,8 @@ - [Investment Appraisal](model/investment.md) - [Model Diagrams](model/model_diagrams.md) - [Glossary](glossary.md) -- [Developer Guide](developer_guide.md) +- [Developer Guide](developer_guide/README.md) + - [Setting up your development environment](developer_guide/setup.md) + - [Building and developing MUSE2](developer_guide/coding.md) + - [Developing the documentation](developer_guide/docs.md) - [API documentation](./api/muse2/README.md) diff --git a/docs/developer_guide.md b/docs/developer_guide.md deleted file mode 100644 index 0d0cd089a..000000000 --- a/docs/developer_guide.md +++ /dev/null @@ -1,280 +0,0 @@ -# Developer Guide - -This is a guide for those who wish to contribute to the MUSE2 project or make local changes to -the code. - -[The API documentation is available here.](./api/muse2) - -## Background: The Rust programming language - -MUSE2 is written using [Rust], which is a high-performance, compiled language. If you have used -other compiled languages, such as C++, many of the concepts will be familiar. One feature which -distinguishes it from other languages like C and C++, however, is that [undefined behaviour], such -as [memory safety] bugs, are not possible, provided you keep to the [safe subset] of the language. -This means you can have the performance benefits of using a low-level language like C, with the -safety guarantees and much of the convenience of a higher-level language like Python. - -There is much high quality documentation available for learning Rust, but it is probably best to -start with [The Rust Programming Language book], which is freely available online. - -[Rust]: https://www.rust-lang.org/ -[undefined behaviour]: https://en.wikipedia.org/wiki/Undefined_behavior -[memory safety]: https://www.memorysafety.org/docs/memory-safety/ -[safe subset]: https://doc.rust-lang.org/nomicon/meet-safe-and-unsafe.html -[The Rust Programming Language book]: https://doc.rust-lang.org/book/ - -## Installing developer tools - -To develop MUSE2 locally you will need the following components: - -- [Git] -- Rust development tools -- C++ development tools (needed for bindings to the [HiGHS] solver) - -Optional requirements: - -- [Just] (recommended) -- [uv] (required for `pre-commit` and file format documentation) - -You can either install the necessary developer tools locally on your machine manually (a bare metal -installation) or use the provided [development container]. Bare metal installation should generally -be preferred if you plan on doing substantial development, as you should get better performance -locally (and therefore shorter compile times), as well as making it easier to interact with your -local filesystem. Development containers provide a mechanism for installing all the tools you will -need (into a [Docker] container) and are generally used either via [Visual Studio Code] running -locally or [GitHub Codespaces], which run on GitHub-provided virtual machines running remotely. - -We provide a [justfile] for some common developer tasks. - -[Git]: https://git-scm.com/ -[HiGHS]: https://highs.dev/ -[Just]: https://github.com/casey/just -[uv]: https://docs.astral.sh/uv/ -[development container]: https://devcontainers.github.io/ -[Docker]: https://www.docker.com/ -[Visual Studio Code]: https://code.visualstudio.com/ -[GitHub Codespaces]: https://github.com/features/codespaces -[justfile]: ../justfile - -### Option 1: Bare metal installation - -#### Installing the Rust toolchain - -We recommend that developers use `rustup` to install the Rust toolchain. Follow the instructions on -[the `rustup` website](https://rustup.rs/). - -Once you have done so, select the `stable` toolchain (used by this project) as your default with: - -```sh -rustup default stable -``` - -As the project uses the latest stable toolchain, you may see build errors if your toolchain is out -of date. You can update to the latest version with: - -```sh -rustup update stable -``` - -#### Installing C++ tools for HiGHS - -The [`highs-sys`] crate requires a C++ compiler and CMake to be installed on your system. -These may be installed already, but if you encounter errors during the build process for `highs-sys` -(e.g. "Unable to find libclang"), you should follow [the instructions in the `highs-sys` -repository][highs-sys-repo]. - -[`highs-sys`]: https://crates.io/crates/highs-sys -[highs-sys-repo]: https://github.com/rust-or/highs-sys#building-highs - -### Option 2: Developing inside a container - -If you wish to use the development container locally with Visual Studio Code, you should first -install the [Dev Containers extension]. Note you will also need Docker to be installed locally. For -more information, see [the documentation]. - -You can use GitHub Codespaces to develop directly from your web browser. For more information, -please see [GitHub's guide]. When you first create your Codespace, you will be asked whether you -wish to install the recommended extensions and you should choose "yes". - -[Dev Containers extension]: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers -[the documentation]: https://code.visualstudio.com/docs/devcontainers/containers -[GitHub's guide]: https://docs.github.com/en/codespaces/developing-in-a-codespace/developing-in-a-codespace - -## Downloading the MUSE2 source code - -Unless you are developing in a GitHub Codespace (see above), you will need to download the MUSE2 -source code to your local machine before you can develop it. Like many projects, MUSE2 is stored -in a Git repository [hosted on GitHub]. Many IDEs, such as Visual Studio Code, provide an interface -to clone Git repositories, but you can also use the Git command-line tool ([see installation -instructions]), like so: - -```sh -git clone https://github.com/EnergySystemsModellingLab/MUSE2 -``` - -The source code will now be available in a folder named `MUSE2`. - -[hosted on GitHub]: https://github.com/EnergySystemsModellingLab/MUSE2 -[see installation instructions]: https://git-scm.com/downloads - -## Working with the project - -To build the project, run: - -```sh -cargo build -``` - -Note that if you just want to build-test the project (i.e. check for errors and warnings) without -building an executable, you can use the `cargo check` command, which is much faster. - -To run MUSE2 with the "simple" example, you can run: - -```sh -cargo run run examples/simple -``` - -(Note the two `run`s. The first is for `cargo` and the second is passed as an argument to the built -`muse2` program.) - -Tests can be run with: - -```sh -cargo test -``` - -More information is available in [the official `cargo` book](https://doc.rust-lang.org/cargo/). - -## Checking test coverage - -We use [Codecov](https://about.codecov.io/) to check whether pull requests introduce code without -tests. - -To check coverage locally (i.e. to make sure newly written code has tests), we recommend using -[cargo-llvm-cov](https://github.com/taiki-e/cargo-llvm-cov). - -It can be installed with: - -```sh -cargo install cargo-llvm-cov -``` - -Once installed, you can use it like so: - -```sh -cargo llvm-cov --open -``` - -Alternatively, you can use Just: - -```sh -just coverage --open -``` - -This will generate a report in HTML format showing which lines are not currently covered by tests -and open it in your default browser. - -## Developing the documentation - -You can make changes to the documentation without having any additional tools installed, however, -you will if you wish to view your changes locally. - -For developing the main documentation, you will need [mdBook] installed (see below) and for the file -format documentation, you will need [uv]. - -If you have all the necessary tools installed and wish to build all of the documentation, you can -run: - -```sh -just build-docs -``` - -However, you will likely want to build only part of the documentation, which you can do by passing -another argument to this command, e.g.: - -```sh -just build-docs file-format -``` - -To see the possible recipes, run: - -```sh -just --list build-docs -``` - -[mdBook]: https://rust-lang.github.io/mdBook/ - -### The book - -We use [mdBook](https://rust-lang.github.io/mdBook/) for generating technical documentation. - -If you are developing the documentation locally, you may want to check that your changes render -correctly (especially if you are working with equations). - -To do this, you first need to install mdBook: - -```sh -cargo install mdbook -``` - -You can then view the documentation in your browser like so: - -```sh -mdbook serve -o -``` - -### Documenting file formats - -Documentation for file formats of different input and output files used by MUSE2 is automatically -generated from schemas, stored in the -[`schemas/`](https://github.com/EnergySystemsModellingLab/MUSE2/tree/main/schemas) folder. - -Files are either in [TOML](https://toml.io/en/) or -[CSV](https://en.wikipedia.org/wiki/Comma-separated_values) format. For TOML files, we use [JSON -schemas](https://json-schema.org/) and for CSV files we use [table -schemas](https://specs.frictionlessdata.io//table-schema/) (a similar format). - -The documentation is generated with the -[`docs/file_formats/generate_docs.py`](https://github.com/EnergySystemsModellingLab/MUSE2/tree/main/docs/file_formats/generate_docs.py) -script. To generate all file format docs, run: - -```sh -just build-docs file-format -``` - -To generate just one kind of docs (e.g. for input files only), run: - -```sh -just build-docs file-format input -``` - -### Recreate the `command_line_help.md` file - -This file is created automatically. In order to examine the output locally, run: - -```sh -just build-docs cli-help -``` - -The file will be written to `docs/command_line_help.md`. - -## Pre-Commit hooks - -We use [`pre-commit`] to automatically run a number of hooks for this repository when a new Git -commit is made. You can run `pre-commit` via our `justfile`, provided you have `uv` installed. - -You can enable `pre-commit` for this repository with: - -```sh -just pre-commit install -``` - -Thereafter, a series of checks should be run every time you commit with Git. In addition, the -`pre-commit` hooks are also run as part of the CI pipeline. - -Note: you may get errors due to the [`clippy`] hook failing. In this case, you may be able to -automatically fix them by running `cargo clipfix` (which we have defined as an alias in -[`.cargo/config.toml`]). - -[`clippy`]: https://doc.rust-lang.org/clippy -[`.cargo/config.toml`]: https://github.com/EnergySystemsModellingLab/MUSE2/blob/main/.cargo/config.toml diff --git a/docs/developer_guide/README.md b/docs/developer_guide/README.md new file mode 100644 index 000000000..7492ec709 --- /dev/null +++ b/docs/developer_guide/README.md @@ -0,0 +1,6 @@ +# Developer Guide + +This is a guide for those who wish to contribute to the MUSE2 project or make local changes to +the code. + +[The API documentation is available here.](../api/muse2/) diff --git a/docs/developer_guide/coding.md b/docs/developer_guide/coding.md new file mode 100644 index 000000000..4496219be --- /dev/null +++ b/docs/developer_guide/coding.md @@ -0,0 +1,76 @@ +# Building and developing MUSE2 + +## Background: The Rust programming language + +MUSE2 is written using [Rust], which is a high-performance, compiled language. If you have used +other compiled languages, such as C++, many of the concepts will be familiar. One feature which +distinguishes it from other languages like C and C++, however, is that [undefined behaviour], such +as [memory safety] bugs, are not possible, provided you keep to the [safe subset] of the language. +This means you can have the performance benefits of using a low-level language like C, with the +safety guarantees and much of the convenience of a higher-level language like Python. + +There is much high quality documentation available for learning Rust, but it is probably best to +start with [The Rust Programming Language book], which is freely available online. + +[Rust]: https://www.rust-lang.org/ +[undefined behaviour]: https://en.wikipedia.org/wiki/Undefined_behavior +[memory safety]: https://www.memorysafety.org/docs/memory-safety/ +[safe subset]: https://doc.rust-lang.org/nomicon/meet-safe-and-unsafe.html +[The Rust Programming Language book]: https://doc.rust-lang.org/book/ + +## Building MUSE2 + +To build the project, run: + +```sh +cargo build +``` + +Note that if you just want to build-test the project (i.e. check for errors and warnings) without +building an executable, you can use the `cargo check` command, which is much faster. + +To run MUSE2 with the "simple" example, you can run: + +```sh +cargo run run examples/simple +``` + +(Note the two `run`s. The first is for `cargo` and the second is passed as an argument to the built +`muse2` program.) + +Tests can be run with: + +```sh +cargo test +``` + +More information is available in [the official `cargo` book](https://doc.rust-lang.org/cargo/). + +## Checking test coverage + +We use [Codecov](https://about.codecov.io/) to check whether pull requests introduce code without +tests. + +To check coverage locally (i.e. to make sure newly written code has tests), we recommend using +[cargo-llvm-cov](https://github.com/taiki-e/cargo-llvm-cov). + +It can be installed with: + +```sh +cargo install cargo-llvm-cov +``` + +Once installed, you can use it like so: + +```sh +cargo llvm-cov --open +``` + +Alternatively, you can use Just: + +```sh +just coverage --open +``` + +This will generate a report in HTML format showing which lines are not currently covered by tests +and open it in your default browser. diff --git a/docs/developer_guide/docs.md b/docs/developer_guide/docs.md new file mode 100644 index 000000000..77b011e9a --- /dev/null +++ b/docs/developer_guide/docs.md @@ -0,0 +1,86 @@ +# Developing the documentation + +You can make changes to the documentation without installing any additional tools, however, you may +wish to do so in order to view your changes locally. + +For developing the main documentation, you will need [mdBook] installed (see below) and for the file +format documentation, you will need [uv]. We also recommend that you install [Just] (the +instructions below assume it is present). + +If you have all the necessary tools installed and wish to build all of the documentation, you can +run: + +```sh +just build-docs +``` + +However, you will likely want to build only part of the documentation, which you can do by passing +another argument to this command, e.g.: + +```sh +just build-docs file-format +``` + +To see the possible recipes, run: + +```sh +just --list build-docs +``` + +[mdBook]: https://rust-lang.github.io/mdBook/ +[uv]: https://docs.astral.sh/uv/ +[Just]: https://github.com/casey/just + +## The book + +We use [mdBook](https://rust-lang.github.io/mdBook/) for generating technical documentation. + +If you are developing the documentation locally, you may want to check that your changes render +correctly (especially if you are working with equations). + +To do this, you first need to install mdBook: + +```sh +cargo install mdbook +``` + +You can then view the documentation in your browser like so: + +```sh +mdbook serve -o +``` + +## Documenting file formats + +Documentation for file formats of different input and output files used by MUSE2 is automatically +generated from schemas, stored in the +[`schemas/`](https://github.com/EnergySystemsModellingLab/MUSE2/tree/main/schemas) folder. + +Files are either in [TOML](https://toml.io/en/) or +[CSV](https://en.wikipedia.org/wiki/Comma-separated_values) format. For TOML files, we use [JSON +schemas](https://json-schema.org/) and for CSV files we use [table +schemas](https://specs.frictionlessdata.io//table-schema/) (a similar format). + +The documentation is generated with the +[`docs/file_formats/generate_docs.py`](https://github.com/EnergySystemsModellingLab/MUSE2/tree/main/docs/file_formats/generate_docs.py) +script. To generate all file format docs, run: + +```sh +just build-docs file-format +``` + +To generate just one kind of docs (e.g. for input files only), run: + +```sh +just build-docs file-format input +``` + +## Generating the `command_line_help.md` file + +This file is created automatically. In order to examine the output locally, run: + +```sh +just build-docs cli-help +``` + +The file will be written to `docs/command_line_help.md`. diff --git a/docs/developer_guide/setup.md b/docs/developer_guide/setup.md new file mode 100644 index 000000000..38faf9d67 --- /dev/null +++ b/docs/developer_guide/setup.md @@ -0,0 +1,117 @@ +# Setting up your development environment + +To develop MUSE2 locally you will need the following components: + +- [Git] +- Rust development tools +- C++ development tools (needed for bindings to the [HiGHS] solver) + +Optional requirements: + +- [Just] (recommended) +- [uv] (required for [pre-commit] and file format documentation) + +You can either install the necessary developer tools locally on your machine manually (a bare metal +installation) or use the provided [development container]. Bare metal installation should generally +be preferred if you plan on doing substantial development, as you should get better performance +locally (and therefore shorter compile times), as well as making it easier to interact with your +local filesystem. Development containers provide a mechanism for installing all the tools you will +need (into a [Docker] container) and are generally used either via [Visual Studio Code] running +locally or [GitHub Codespaces], which run on GitHub-provided virtual machines running remotely. + +We provide a [justfile] for some common developer tasks. + +[Git]: https://git-scm.com/ +[HiGHS]: https://highs.dev/ +[Just]: https://github.com/casey/just +[uv]: https://docs.astral.sh/uv/ +[pre-commit]: https://pre-commit.com/ +[development container]: https://devcontainers.github.io/ +[Docker]: https://www.docker.com/ +[Visual Studio Code]: https://code.visualstudio.com/ +[GitHub Codespaces]: https://github.com/features/codespaces +[justfile]: ../../justfile + +## Installing tools + +### Option 1: Bare metal installation + +#### Installing the Rust toolchain + +We recommend that developers use `rustup` to install the Rust toolchain. Follow the instructions on +[the `rustup` website](https://rustup.rs/). + +Once you have done so, select the `stable` toolchain (used by this project) as your default with: + +```sh +rustup default stable +``` + +As the project uses the latest stable toolchain, you may see build errors if your toolchain is out +of date. You can update to the latest version with: + +```sh +rustup update stable +``` + +#### Installing C++ tools for HiGHS + +The [`highs-sys`] crate requires a C++ compiler and CMake to be installed on your system. +These may be installed already, but if you encounter errors during the build process for `highs-sys` +(e.g. "Unable to find libclang"), you should follow [the instructions in the `highs-sys` +repository][highs-sys-repo]. + +[`highs-sys`]: https://crates.io/crates/highs-sys +[highs-sys-repo]: https://github.com/rust-or/highs-sys#building-highs + +### Option 2: Developing inside a container + +If you wish to use the development container locally with Visual Studio Code, you should first +install the [Dev Containers extension]. Note you will also need Docker to be installed locally. For +more information, see [the documentation]. + +You can use GitHub Codespaces to develop directly from your web browser. For more information, +please see [GitHub's guide]. When you first create your Codespace, you will be asked whether you +wish to install the recommended extensions and you should choose "yes". + +[Dev Containers extension]: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers +[the documentation]: https://code.visualstudio.com/docs/devcontainers/containers +[GitHub's guide]: https://docs.github.com/en/codespaces/developing-in-a-codespace/developing-in-a-codespace + +## Downloading the MUSE2 source code + +Unless you are developing in a GitHub Codespace (see above), you will need to download the MUSE2 +source code to your local machine before you can develop it. Like many projects, MUSE2 is stored +in a Git repository [hosted on GitHub]. Many IDEs, such as Visual Studio Code, provide an interface +to clone Git repositories, but you can also use the Git command-line tool ([see installation +instructions]), like so: + +```sh +git clone https://github.com/EnergySystemsModellingLab/MUSE2 +``` + +The source code will now be available in a folder named `MUSE2`. + +[hosted on GitHub]: https://github.com/EnergySystemsModellingLab/MUSE2 +[see installation instructions]: https://git-scm.com/downloads + +## Pre-Commit hooks + +We use [pre-commit] to automatically run a number of hooks for this repository when a new Git +commit is made. You can run `pre-commit` via our `justfile`, provided you have `uv` installed. + +You can enable `pre-commit` for this repository with: + +```sh +just pre-commit install +``` + +Thereafter, a series of checks should be run every time you commit with Git. In addition, the +`pre-commit` hooks are also run as part of the CI pipeline. + +Note: you may get errors due to the [`clippy`] hook failing. In this case, you may be able to +automatically fix them by running `cargo clipfix` (which we have defined as an alias in +[`.cargo/config.toml`]). + +[`clippy`]: https://doc.rust-lang.org/clippy +[`.cargo/config.toml`]: https://github.com/EnergySystemsModellingLab/MUSE2/blob/main/.cargo/config.toml From 671478febee14e32be491a6dd0aed52827eca2a0 Mon Sep 17 00:00:00 2001 From: Alex Dewar Date: Fri, 9 Jan 2026 12:20:01 +0000 Subject: [PATCH 5/6] Fix: Developers no longer need to manually install `stable` toolchain --- docs/developer_guide/setup.md | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/docs/developer_guide/setup.md b/docs/developer_guide/setup.md index 38faf9d67..c972bd61a 100644 --- a/docs/developer_guide/setup.md +++ b/docs/developer_guide/setup.md @@ -41,18 +41,12 @@ We provide a [justfile] for some common developer tasks. We recommend that developers use `rustup` to install the Rust toolchain. Follow the instructions on [the `rustup` website](https://rustup.rs/). -Once you have done so, select the `stable` toolchain (used by this project) as your default with: +This project defines the required version of the Rust toolchain in [`rust-toolchain.toml`]. The +first time you attempt to run `cargo` (see [Building and developing MUSE2]), this toolchain should +be downloaded and installed automatically by `rustup`. -```sh -rustup default stable -``` - -As the project uses the latest stable toolchain, you may see build errors if your toolchain is out -of date. You can update to the latest version with: - -```sh -rustup update stable -``` +[`rust-toolchain.toml`]: https://github.com/EnergySystemsModellingLab/MUSE2/blob/main/rust-toolchain.toml +[Building and developing MUSE2]: ./coding.md #### Installing C++ tools for HiGHS From 673a81a3c31cf30218c30640f94f456ef94e958b Mon Sep 17 00:00:00 2001 From: Alex Dewar Date: Fri, 9 Jan 2026 12:21:18 +0000 Subject: [PATCH 6/6] Fix justfile: Unused `ARGS` --- justfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/justfile b/justfile index 374a7b3cc..102a1d461 100644 --- a/justfile +++ b/justfile @@ -16,7 +16,7 @@ help: # Generate test coverage in HTML format coverage *ARGS: - @cargo llvm-cov --html + @cargo llvm-cov --html {{ARGS}} # Regenerate data for regression tests regenerate_test_data: