Skip to content

Explanation of Documentation Setup

Jump to bottom
Stefan Appelhoff edited this page Dec 7, 2023 · 6 revisions

2020-03-24 to date

relevant issues and PRs:

General workflow:

  • CircleCI builds the documentation on each PR and uploads artifacts for inspection
  • once a PR is merged and CircleCI thus runs on the main branch, the deploy job is being run
    • the deploy job takes the built docs and pushes them to a dev directory on the gh-pages branch, leaving all other files and other folders alone
  • On the gh-pages branch there are several other subdirectories next to the already mentioned dev directory:
    • stable
    • v0.1
    • v0.2
    • etc.
    • --> Each of these directories contains the corresponding docs, manually built and pushed to the gh-pages branch by a maintainer who performs a release
  • Next to the doc subdirectories, there are two more files, which were added manually:
    • index.html, which re-directs users to the stable docs in the stable subdirectory
    • .nojekyll, which prevents GitHub from performing any jekyll related jobs
  • Each documentation contains a dropdown menu (supplied through a template extension) to select a different version ... linking to the docs in another subdirectory
    • Note: A given version always contains a link to stable and dev version
    • Note: A given version furthermore contains links to all previous versions, but NOT the following versions.
    • E.g., v0.2 has links to stable (which could currently be v0.6), dev, and v0.1 ... but not versions v0.3, v0.4, v0.5

further notes:

  • the currently stable docs are actually duplicated:
    • once in their own vX.Y directory
    • another time in the stable directory
  • this is important to get a meaningful link: mne.tools/mne-bids/stable instead of .../vX.Y

2017-04-24 until 2020-03-24

General workflow:

  • The docs were being built via a make install call and then uploaded (first manually, but later on via CircleCI) to the gh-pages branch.
  • This was done upon each stable release, hence only the stable docs were available.
  • Later on (2019-07-09), the latest (dev) docs were available through the CircleCI build artifacts, which can be linked to by constructing a link with some keywords:
    • https://circleci.com/api/v1.1/project/github/mne-tools/mne-bids/latest/artifacts/0/html/index.html?branch=main
    • The condition for this is, that the last CircleCI job to run in a build will produce the html/index.html artifact.
    • see #216
  • Issue: Previous doc versions were not available, no dropdown menu to select dev vs. stable docs

Clone this wiki locally