diff --git a/Cargo.toml b/Cargo.toml index b97990c76..ec6c75eea 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -4,7 +4,7 @@ version = "2.1.0" authors = ["Hawkes Research Group @ Chemical Engineering, Imperial College London ", "Imperial College London RSE Team "] edition = "2024" description = "A tool for running simulations of energy systems" -documentation = "https://energysystemsmodellinglab.github.io/MUSE2" +homepage = "https://energysystemsmodellinglab.github.io/MUSE2" readme = "README.md" repository = "https://github.com/EnergySystemsModellingLab/MUSE2" license = "GPL-3.0-only" diff --git a/build-docs.just b/build-docs.just index 8c54d046d..8879684fa 100644 --- a/build-docs.just +++ b/build-docs.just @@ -42,9 +42,12 @@ header: @echo Generating theme/header.hbs @uv run docs/generate_header.py -# Build documentation for previous releases -old: header - @# Clean output dir - @rm -rf book/release +# Move the dev docs to the same level as the old docs +move-dev: header book api + @echo Moving dev docs to /dev + @uv run docs/move_dev_docs.py +# Build documentation for previous releases +old: move-dev + @echo Building old versions of docs @uv run docs/build_old_docs.py diff --git a/docs/build_old_docs.py b/docs/build_old_docs.py index 6ad3f0cad..8f302a1ac 100755 --- a/docs/build_old_docs.py +++ b/docs/build_old_docs.py @@ -85,7 +85,7 @@ def build_docs_for_release(release: str, repo_path: Path, outdir: Path) -> None: def build_old_docs() -> None: """Build documentation for previous releases.""" - outdir = REPO_ROOT / "book" / "release" + outdir = REPO_ROOT / "book" outdir.mkdir(parents=True, exist_ok=True) # Clone this repo to a temporary directory diff --git a/docs/move_dev_docs.py b/docs/move_dev_docs.py new file mode 100755 index 000000000..1abde1df7 --- /dev/null +++ b/docs/move_dev_docs.py @@ -0,0 +1,35 @@ +#!/usr/bin/env python3 +# +# A script to move the development docs into a /dev directory + +import shutil +from pathlib import Path +from tempfile import TemporaryDirectory + +from release import get_releases + +REPO_ROOT = Path(__file__).parent.parent.absolute() + + +def move_to_dev() -> None: + """Move the built documentation output (`book/`) into `book/dev/`.""" + bookdir = REPO_ROOT / "book" + outdir = REPO_ROOT / "book" / "dev" + + with TemporaryDirectory() as tmpdir: + # Move book to temporary directory + shutil.move(bookdir, tmpdir) + shutil.move(Path(tmpdir) / "book", outdir) + + # Redirect to stable (most recent) version of docs + with (bookdir / "index.html").open("w", encoding="utf-8") as f: + f.write(f""" + +""") + + +if __name__ == "__main__": + move_to_dev() diff --git a/docs/release_notes/v2.1.0.md b/docs/release_notes/v2.1.0.md index 9ddec4242..0f38997dc 100644 --- a/docs/release_notes/v2.1.0.md +++ b/docs/release_notes/v2.1.0.md @@ -134,14 +134,14 @@ previous versions of MUSE2. [#1205]: https://github.com/EnergySystemsModellingLab/MUSE2/pull/1205 -[`demand.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/release/v2.1.0/file_formats/input_files.html#demandcsv -[`processes.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/release/v2.1.0/file_formats/input_files.html#processescsv -[`process_flows.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/release/v2.1.0/file_formats/input_files.html#process_flowscsv -[`process_availabilities.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/release/v2.1.0/file_formats/input_files.html#process_availabilitiescsv -[`process_parameters.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/release/v2.1.0/file_formats/input_files.html#process_parameterscsv -[`process_investment_constraints.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/release/v2.1.0/file_formats/input_files.html#process_investment_constraintscsv -[`commodities.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/release/v2.1.0/file_formats/input_files.html#commoditiescsv -[`commodity_levies.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/release/v2.1.0/file_formats/input_files.html#commodity_leviescsv -[`model.toml`]: https://energysystemsmodellinglab.github.io/MUSE2/release/v2.1.0/file_formats/input_files.html#model-parameters-modeltoml -[`assets.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/release/v2.1.0/file_formats/input_files.html#assetscsv -[`settings.toml`]: https://energysystemsmodellinglab.github.io/MUSE2/release/v2.1.0/file_formats/program_settings.html +[`demand.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.1.0/file_formats/input_files.html#demandcsv +[`processes.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.1.0/file_formats/input_files.html#processescsv +[`process_flows.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.1.0/file_formats/input_files.html#process_flowscsv +[`process_availabilities.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.1.0/file_formats/input_files.html#process_availabilitiescsv +[`process_parameters.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.1.0/file_formats/input_files.html#process_parameterscsv +[`process_investment_constraints.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.1.0/file_formats/input_files.html#process_investment_constraintscsv +[`commodities.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.1.0/file_formats/input_files.html#commoditiescsv +[`commodity_levies.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.1.0/file_formats/input_files.html#commodity_leviescsv +[`model.toml`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.1.0/file_formats/input_files.html#model-parameters-modeltoml +[`assets.csv`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.1.0/file_formats/input_files.html#assetscsv +[`settings.toml`]: https://energysystemsmodellinglab.github.io/MUSE2/v2.1.0/file_formats/program_settings.html diff --git a/docs/templates/header.hbs.jinja b/docs/templates/header.hbs.jinja index 889ca33db..6e90802bc 100644 --- a/docs/templates/header.hbs.jinja +++ b/docs/templates/header.hbs.jinja @@ -90,30 +90,20 @@ var labelText = document.getElementById("version-label-text"); var list = document.getElementById("version-list"); - var versionMatch = /\/release\/(v[\d.]+)\//.exec(path); + var versionMatch = /\/(v[\d.]+)\//.exec(path); var isDev = !versionMatch; - var currentVersion = isDev ? "development" : versionMatch[1]; + var currentVersion = isDev ? "dev" : versionMatch[1]; var isStable = false; // Build version list var pathToRoot = "{% raw %}{{path_to_root}}{% endraw %}"; var versions = [ - { label: "development", stable: false }, + { label: "dev", stable: false }, {%- for release in releases %} { label: "{{ release.label }}", stable: {{ release.stable|lower }} }, {%- endfor %} ]; - function hrefFor(label) { - if (isDev) { - if (label === "development") return pathToRoot; - return pathToRoot + "release/" + label + "/index.html"; - } - // Old versioned docs (e.g. /release/v2.0.0/) - if (label === "development") return pathToRoot + "../../index.html"; - return pathToRoot + "../" + label + "/index.html"; - } - versions.forEach(function (v) { var li = document.createElement("li"); @@ -130,7 +120,7 @@ li.appendChild(strong); } else { var a = document.createElement("a"); - a.href = hrefFor(v.label); + a.href = pathToRoot + "../" + v.label + "/index.html"; a.textContent = versionLabel; li.appendChild(a); } diff --git a/schemas/input/model.yaml b/schemas/input/model.yaml index 1380ed978..cbfffd89d 100644 --- a/schemas/input/model.yaml +++ b/schemas/input/model.yaml @@ -63,10 +63,8 @@ properties: type: object description: | Used for setting custom HiGHS options. As this is unsafe, it requires setting - `please_give_me_broken_results` to true. For more information, see the relevant [section of - the developer documentation][highs-opts-docs]. - - [highs-opts-docs]: https://energysystemsmodellinglab.github.io/MUSE2/developer_guide/custom_highs_options.html + `please_give_me_broken_results` to true. For more information, see the relevant + [section of the developer documentation](../developer_guide/custom_highs_options.html). properties: global_options: type: object diff --git a/src/cli.rs b/src/cli.rs index 1c85cf56f..785d7a17a 100644 --- a/src/cli.rs +++ b/src/cli.rs @@ -21,9 +21,7 @@ use settings::SettingsSubcommands; version, about, after_help = concat!( - "For more detailed documentation on this version of MUSE2, see: https://energysystemsmodellinglab.github.io/MUSE2/release/v", - env!("CARGO_PKG_VERSION"), - "/" + "For more detailed documentation on this version of MUSE2, see: ", crate::docs_url!() ) )] struct Cli { diff --git a/src/lib.rs b/src/lib.rs index 47bf143a0..f3501fe43 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -4,6 +4,23 @@ /// The main GitHub issues page for MUSE2 pub const ISSUES_URL: &str = concat!(env!("CARGO_PKG_REPOSITORY"), "/issues"); +/// A macro to get a url to the most recent version of the documentation +#[macro_export] +macro_rules! docs_url { + () => { + docs_url!("") + }; + ($suffix:literal) => { + concat!( + env!("CARGO_PKG_HOMEPAGE"), + "/v", + env!("CARGO_PKG_VERSION"), + "/", + $suffix + ) + }; +} + use dirs::config_dir; use std::path::PathBuf; diff --git a/src/settings.rs b/src/settings.rs index 6697b9416..6fe834e8e 100644 --- a/src/settings.rs +++ b/src/settings.rs @@ -23,8 +23,9 @@ const DEFAULT_SETTINGS_FILE_HEADER: &str = concat!( # \tmuse2 settings show-default # # For information about the possible settings, visit: -# \thttps://energysystemsmodellinglab.github.io/MUSE2/file_formats/program_settings.html -" +# \t", + crate::docs_url!("file_formats/program_settings.html"), + "\n" ); /// Get the path to where the settings file will be read from diff --git a/src/simulation/optimisation.rs b/src/simulation/optimisation.rs index 8b5f49a57..53d20c7e8 100644 --- a/src/simulation/optimisation.rs +++ b/src/simulation/optimisation.rs @@ -511,7 +511,7 @@ fn get_parent_or_self(assets: &[AssetRef]) -> Vec { /// /// For a detailed description, please see the [dispatch optimisation formulation][1]. /// -/// [1]: https://energysystemsmodellinglab.github.io/MUSE2/model/dispatch_optimisation.html +#[doc = concat!("[1]: ", crate::docs_url!("/model/dispatch_optimisation.html"))] #[must_use = "Must call run() method on DispatchRun struct"] pub struct DispatchRun<'model, 'run> { model: &'model Model, diff --git a/src/simulation/optimisation/constraints.rs b/src/simulation/optimisation/constraints.rs index ac7d710ff..d258d4cf6 100644 --- a/src/simulation/optimisation/constraints.rs +++ b/src/simulation/optimisation/constraints.rs @@ -113,7 +113,7 @@ where /// commodity-balance constraint added to `problem` and `keys` lists the /// `(commodity, region, time_selection)` entries in the same order as the rows. /// -/// [1]: https://energysystemsmodellinglab.github.io/MUSE2/model/dispatch_optimisation.html#commodity-balance-for--cin-mathbfcmathrmsed- +#[doc = concat!("[1]: ", crate::docs_url!("model/dispatch_optimisation.html#commodity-balance-for--cin-mathbfcmathrmsed-"))] fn add_commodity_balance_constraints<'a, I>( problem: &mut Problem, variables: &VariableMap, @@ -207,7 +207,7 @@ where /// (upper and lower bounds) are added per selection; in that case the same key is /// stored twice to match the solver ordering. /// -/// [1]: https://energysystemsmodellinglab.github.io/MUSE2/model/dispatch_optimisation.html#a4-constraints-capacity--availability-for-standard-assets--a-in-mathbfastd- +#[doc = concat!("[1]: ", crate::docs_url!("model/dispatch_optimisation.html#a4-constraints-capacity--availability-for-standard-assets--a-in-mathbfastd-"))] fn add_activity_constraints<'a, I>( problem: &mut Problem, variables: &VariableMap, diff --git a/src/simulation/prices.rs b/src/simulation/prices.rs index 487fd6161..9269ca131 100644 --- a/src/simulation/prices.rs +++ b/src/simulation/prices.rs @@ -1,6 +1,6 @@ //! Code for calculating commodity prices used by the simulation. //! -//! See +#![doc = concat!("See <", crate::docs_url!("/model/prices.html"), ">")] use crate::asset::AssetRef; use crate::commodity::{CommodityID, CommodityMap, PricingStrategy}; use crate::model::Model; diff --git a/tests/cli.rs b/tests/cli.rs index 4cd5ee69a..7087e03ee 100644 --- a/tests/cli.rs +++ b/tests/cli.rs @@ -17,7 +17,7 @@ fn check_help_command() { assert!( get_muse2_stdout(&["help"]).contains( format!( - "https://energysystemsmodellinglab.github.io/MUSE2/release/v{}/", + "https://energysystemsmodellinglab.github.io/MUSE2/v{}/", env!("CARGO_PKG_VERSION") ) .as_str()