Documentation and website deployment#
Note
This guide is intended for napari core contributors and is not required reading for regular contributors. If you’re looking for information on how to contribute to the documentation, see Contributing Documentation.
The napari documentation and website sources are spread over three repositories, and these are connected and used to generate the documentation and website through several CI workflows detailed below.
-
Workflow file:
build_docs.yml
job:
build-and-upload
Pulls in sources from
napari/docs
and builds docs locally. Uploads artifacts to this repo (napari/napari
).This is triggered on every Pull Request and shows up as a “Build PR Docs” check on the PR.
Workflow file:
deploy_docs.yml
job:
build-and-deploy
Triggers
deploy_docs.yml
workflow at the napari/docs repo. Waits for results and reports it.This is triggered on any commit to the
main
branch onnapari/napari
(and consequently triggers a new deployment of thenapari.org
website.)
-
Workflow file:
build_docs.yml
job:
build-and-upload
Pulls in sources from
napari/napari
and builds docs locally. Uploads artifacts to this repo (napari/docs
).This is triggered on every Pull Request and shows up as a “Build PR Docs” check on the PR.
Workflow file:
deploy_docs.yml
job:
build-and-deploy
Builds docs locally and deploys resulting artifacts to GitHub pages at the
gh-pages
branch of napari/napari.github.io.Always deploys to the
dev/
folder onnapari.github.io
(version “latest” on the website).This is triggered on any commit to the
main
branch onnapari/docs
(and consequently triggers a new deployment of thenapari.org
website.)
Note that these file are not identical to the
napari/napari
versions. -
Contains built documentation files (.html) for all versions in the
gh-pages
branch. Auto-deploys togh-pages
on every commit (which in turn happens on every commit to themain
branches of eithernapari/napari
ornapari/docs
).
Notes#
CircleCI is set up in both napari/napari
and napari/docs
, but doesn’t deploy
documentation. It serves to test the docs build and to provide documentation
previews for PRs. The relevant configuration files are:
On
napari/napari
:.circleci/config.yml
: builds documentation and stores artifact in the CircleCI platform.github/workflows/circleci.yml
: adds a link to the documentation preview to each PR.
On
napari/docs
:.circleci/config.yml
: builds documentation and stores artifact in the CircleCI platform.github/workflows/circleci.yml
: adds a link to the documentation preview to each PR.