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
. .venv/bin/activate
uv pip install \
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
To test locally with mkdocs serve
:
to build and deploy the site:
then, provided you have an ssh key set up for authentication with github.com
:
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: