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

for f in ${fn[@]} ; do
    echo "processing $f";
    jupyter nbconvert --to notebook --ExecutePreprocessor.kernel_name=${kernel_name} --execute ${pkg_dir}/notebooks/${f} --output-dir=./
done

Building the site

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

cd $HOME/src/swift-py-doc
uv venv .venv

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

dont forget to update the package(s) instaled 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/swift/bindings/python/swift2/

To test locally with mkdocs serve:

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:

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: