Skip to content

Explanation of Documentation Setup

Jump to bottom
Stefan Appelhoff edited this page Mar 24, 2020 · 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 master 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

Notes on binder:

  • each sphinx-gallery example will have a "binder" link at the bottom (see docs)
  • this binder link will lead to a subdirectory on the gh-pages branch through the filepath_prefix argument (see conf.py)
  • the filepath_prefix argument is constructed by parsing the current __version__
    • if it contains dev the filepath_prefix becomes dev, leading to the dev docs
    • else if is assumed that __version__ points to a stable release X.Y and we prepend a v, leading to the vX.Y docs

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, and it's also important for the binder setup to work

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=master
    • 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