Skip to content

Building and deploying documentation

What gets committed

  • Source: docs/ (Markdown, API stubs, assets), mkdocs.yml, and tutorial notebooks under notebooks/ (synced into docs/notebooks/ before a build).
  • Not committed: site/ (MkDocs HTML output) and .cache/ (mkdocs-jupyter cache). Both are listed in .gitignore.

Local preview

pip install -e ".[docs]"
bash scripts/sync_notebooks_for_docs.sh
mkdocs serve

Open the URL MkDocs prints (usually http://127.0.0.1:8000).

Read the Docs (hosted site)

Documentation is built and published by Read the Docs using .readthedocs.yaml at the repository root.

On each build, RTD:

  1. Installs the package with docs extras (pip install -e ".[docs]").
  2. Runs scripts/sync_notebooks_for_docs.sh so docs/notebooks/ matches notebooks/.
  3. Runs mkdocs build with mkdocs.yml.

The RTD config also runs pip install --no-deps -e . after the docs requirements so the ace_neuro package is importable without pulling CaImAn from PyPI (the hosted site is for documentation only, not full pipeline execution). Local analysis environments should follow Getting started.

Project setup (dashboard): import the GitHub repository in Read the Docs, connect the private repo if needed (private repositories), and point the default branch at your main docs branch. The canonical docs URL is configured in mkdocs.yml as site_url (currently https://ace-neuro.readthedocs.io/en/latest/). If your RTD project slug differs, update site_url and any hardcoded links accordingly.

CI: You can add a GitHub Actions workflow that runs mkdocs build on pushes and pull requests (without deploying); production hosting is typically Read the Docs.

Updating tutorials

Edit files in notebooks/, regenerate or copy into docs/notebooks/ with scripts/sync_notebooks_for_docs.sh, then commit.