Book outline

.github/workflows/linux.yml

@@ -17,7 +17,18 @@ jobs:
     - uses: actions/checkout@v4
       with:
         submodules: true
+
+    - name: Install latest mdbook
+      run: |
+        tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name')
+        url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz"
+        mkdir bin
+        curl -sSL $url | tar -xz --directory=bin
+        echo "$(pwd)/bin" >> $GITHUB_PATH
+
     - name: Build
       run: cargo build --verbose --no-default-features
     - name: Run tests
       run: cargo test --no-default-features
+    - name: Run mdbook tests
+      run: mdbook test ./pywr-book

pywr-book/.gitignore

@@ -0,0 +1 @@
+book

pywr-book/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["James Tomlinson"]
+language = "en"
+multilingual = false
+src = "src"
+title = "The Pywr Book"

pywr-book/src/SUMMARY.md

@@ -0,0 +1,22 @@
+# Summary
+
+- [Introduction](./introduction.md)
+- [Getting started](./getting_started.md)
+  - [Installation](./installation.md)
+  - [Licensing](./licensing.md)
+  - [Related projects](./related_projects.md)
+- [Core concepts](./concepts/README.md)
+  - [The network](./concepts/the-network.md)
+  - [Parameters](./concepts/parameters.md)
+  - [Penalty costs](./concepts/penalty-costs.md)
+  - [Reservoirs](./concepts/reservoirs.md)
+  - [Abstraction licences](./concepts/abstraction-licences.md)
+  - [Scenarios](./concepts/scenarios.md)
+  - [Input data](./concepts/input-data.md)
+- [Extending Pywr](./extending_pywr.md)
+- [Multi-models](./multi_models.md)
+- [Migration guide](./migration_guide.md)
+- [Model management](./model-management/README.md)
+  - [Version control](./model-management/version-control.md)
+  - [Packaging](./model-management/packaging.md)
+  - [Deployment & Docker](./model-management/deployment.md)

pywr-book/src/concepts/README.md

@@ -0,0 +1 @@
+# Core concepts

pywr-book/src/concepts/abstraction-licences.md

@@ -0,0 +1 @@
+# Abstraction licences

pywr-book/src/concepts/input-data.md

@@ -0,0 +1 @@
+# Input data

pywr-book/src/concepts/parameters.md

@@ -0,0 +1 @@
+# Parameters

pywr-book/src/concepts/penalty-costs.md

@@ -0,0 +1 @@
+# Penalty costs

pywr-book/src/concepts/reservoirs.md

@@ -0,0 +1 @@
+# Reservoirs

pywr-book/src/concepts/scenarios.md

@@ -0,0 +1 @@
+# Scenarios

pywr-book/src/concepts/the-network.md

@@ -0,0 +1 @@
+# The network

pywr-book/src/extending_pywr.md

@@ -0,0 +1 @@
+# Getting started

pywr-book/src/getting_started.md

@@ -0,0 +1 @@
+# Getting started

pywr-book/src/installation.md

@@ -0,0 +1 @@
+# Installation

pywr-book/src/introduction.md

@@ -0,0 +1,15 @@
+# Introduction
+
+Welcome to the Pywr book!
+Pywr is an open-source network resource allocation model.
+This book is a collection of documentation and tutorials for using Pywr.
+It should be read alongside the Pywr API documentation.
+
+# What is Pywr?
+
+Pywr is a Rust crate and Python package for building and running water resource models.
+It allows users to construct models of water systems using a network of nodes and links, and other data.
+The model can then be used to simulate the operation of a water system, and to evaluate the performance of the system under different scenarios.
+
+This version is a major update to the original Pywr model, which was written in Python and Cython.
+The new version is written in Rust, and uses Python bindings to expose the functionality to Python.

pywr-book/src/licensing.md

@@ -0,0 +1 @@
+# Licensing

pywr-book/src/related_projects.md

@@ -0,0 +1 @@
+# Related projects