Skip to content

swift-py-doc

This site is to host the documentation for the swift2 python package, which is part of a suite of tools for Streamflow Forecasting.

Updating the content of site

These are notes to "self"

Copy doc files from reference repo

pkg_dir=${HOME}/src/swift/bindings/python/swift2
doc_dir=${HOME}/src/swift-py-doc
declare -a fn=(calibrate_multisite.ipynb \
  calibrate_subcatchments.ipynb \
  calibration_initial_states.ipynb \
  ensemble_model_runs.ipynb \
  error_correction_four_stages.ipynb \
  getting_started.ipynb \
  log_likelihood.ipynb \
  meta_parameters.ipynb \
  muskingum_multilink_calibration.ipynb \
  reservoir_geometry.ipynb)

cd ${doc_dir}
# WARNING: rm -r...
rm -r docs
cp ${pkg_dir}/mkdocs.yml ${doc_dir}/
cp -r ${pkg_dir}/docs ${doc_dir}/
cp ${pkg_dir}/LICENSE.txt ${doc_dir}/docs/license.md


# Iterate through the array 'fn'
for f in "${fn[@]}"; do
  file=${pkg_dir}/notebooks/${f}
  # Check if the file exists
  if [[ ! -f "$file" ]]; then
    echo "File '$file' does NOT exist."
  fi
done
# muskingum_multilink_calibration_explanation.ipynb

mkdir -p ${doc_dir}/docs/notebooks
cd ${doc_dir}/docs/notebooks
rm *.ipynb
cp ${pkg_dir}/notebooks/*.png ./

Execute notebooks in-place

This may take a few minutes to run, esp. if run from debug build.

# kernel_name=hydrofc_release
kernel_name=hydrofc

cd ${doc_dir}/docs/notebooks

for f in ${fn[@]} ; do
    echo "processing $f";
    jupyter nbconvert --to notebook --ExecutePreprocessor.kernel_name=${kernel_name} --execute ${pkg_dir}/notebooks/${f} --output-dir=./
    if [ $? -ne 0 ]; then
        echo "Error: Failed to execute $f"
        break
    fi
done

Building the site

May 2025 moving to use uv to manage the python environment.

# dont recreate: will override existing one
# cd $HOME/src/swift-py-doc
# uv venv .venv

CAUTION: as of June 2026, mkdocs has changed license and architecture with major, breaking change. While mkdocs-llmstxt is not yet ported or has no equivalents. pending on the backlog, beware not to update.

mkdocs, version 1.6.1 from HOME/miniforge3/envs/hydrofc/lib/python3.11/site-packages/mkdocs (Python 3.11)

cd $HOME/src/swift-py-doc
. .venv/bin/activate
uv pip install -U \
  mkdocs= \
  mkdocs-material \
  mkdocstrings  \
  mkdocs-material-extensions \
  mkdocs-jupyter \
  mkdocstrings-python  \
  markdown-callouts \
  mkdocs-llmstxt
# May 2025 I am trying to produce llms.txt files

IMPORTANT dont forget to update the package(s) installed in the venvs, this is what is used to get the doc, not the mamba env. Caught every time.

# NOTE: some changes in the API doc were just not picked up unless you do:
uv pip freeze | grep swift
# uv pip uninstall swift2
uv pip install -e ~/src/datatypes/bindings/python/uchronia
uv pip install -e ~/src/swift/bindings/python/swift2

To test locally with mkdocs serve:

doc_dir=${HOME}/src/swift-py-doc
cd ${doc_dir}
mkdocs serve -w mkdocs.yml -w docs/

to build and deploy the site:

cd ${doc_dir}
mkdocs build --clean --site-dir _build/html --config-file mkdocs.yml

then, provided you have an ssh key set up for authentication with github.com:

# ssh-add
mkdocs gh-deploy --clean --site-dir _build/html --config-file mkdocs.yml

Examples as markdown

We can export the sample notebooks to markdown, with a view to use them as contexts for AI code aids.

Note that is important to NOT output to ${doc_dir}/docs/notebooks, as it messes up the web site layout (see issue 2)

cd ${doc_dir}/docs/notebooks
out_dir=${doc_dir}/attic/docs/notebooks/
mkdir -p ${out_dir} 
for f in ${fn[@]} ; do
    echo "processing $f";
    jupyter nbconvert --to markdown ./${f} --output-dir=${out_dir} 
done

Resources

Grateful for examplars for configuring mkdocs, at least as of 2023 or so:

Python swift2 documentation

Documentation for the Python package swift2, a package for ensemble hydrologic modelling.

Installation

See Onboarding guide for streamflow forecasting software tools

License

The swift2 python package itself is licensed with the BSD 3-Clause Licence

Source code

The package source code "point of truth" is at this private repository, however a copy is also in the repository csiro-hydroinformatics/swift-py-doc.

LLM context files

Using LLMs for development is a best practice way to get started and explore. While LLMs cannot code for you, they can be helpful assistants. You must check, refactor, test, and vet any code any LLM generates for you - but they are helpful productivity tools. The following files will be useful as context for LLMs to build modelling workflows with the swift2 package.

These files follow the proposed /llms.txt standard, and are produced with mkdocs-llmstxt.