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

```bash pkgdir=${HOME}/src/swift/bindings/python/swift2 docdir=${HOME}/src/swift-py-doc declare -a fn=(calibratemultisite.ipynb \ calibratesubcatchments.ipynb \ calibrationinitialstates.ipynb \ ensemblemodelruns.ipynb \ errorcorrectionfourstages.ipynb \ gettingstarted.ipynb \ loglikelihood.ipynb \ metaparameters.ipynb \ muskingummultilinkcalibration.ipynb \ reservoir_geometry.ipynb)

cd ${doc_dir}

WARNING: rm -r...

rm -r docs cp ${pkgdir}/mkdocs.yml ${docdir}/ cp -r ${pkgdir}/docs ${docdir}/ cp ${pkgdir}/LICENSE.txt ${docdir}/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

muskingummultilinkcalibration_explanation.ipynb

mkdir -p ${docdir}/docs/notebooks cd ${docdir}/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.

```sh

kernelname=hydrofcrelease

kernel_name=hydrofc

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

Building the site

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

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

```sh 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.

```sh

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:

sh cd ${doc_dir} mkdocs serve -w mkdocs.yml -w docs/

to build and deploy the site:

bash 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:

sh 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)

sh 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:

• https://github.com/FasterSpeeding/Tanjun/blob/master/mkdocs.yml
• https://github.com/tiangolo/fastapi/blob/master/docs/en/mkdocs.yml