Open Neuro Interface

This documentation's source template was taken from the Spinal HDL project.

The theme is based on the PyData Sphinx Theme.

For more detailed usage instructions, see the Open Ephys Doc Template.

How to build this documentation

Previewing local changes

Due to how sphinx-multiversion is configured (see below), in order to view the local changes that are made, it is necessary to create a file at the top-most level of the repo named "whitelist.txt". This file will be ignored via .gitignore, so it will only exist locally, but it should contain a list of local branches that should be included in the build process.

The contents of the file should only include the names of the branches that should be included. For example, if work is being done on branch issue-85, the whitelist.txt file should contain only the following line:

issue-85

If work is being done on multiple branches, and all of them need to be built simultaneously to preview how the changes are being rendered, then split the list of branches into individual lines like the following example:

issue-85
issue-86

With pipenv (recommended)

Requirements (Python 3):

• pipenv (will automatically download all the project requirements from pypi)

Create a virtual environment with pipenv (will use the Pipfile for installing the necessary packages).

pipenv install

Then you can build the documentation. Note that make html will call sphinx-multiversion and will automatically build all tags and branches as defined in the conf.py file. For more details, see the section on sphinx-multiversion below.

pipenv run make html

If you want to run make multiple times, prepending pipenv run on each command can be annoying. You can spawn a subshell with:

pipenv shell

and then you can use make the usual way.

make html     # for html
make latex    # for latex
make latexpdf # for latex (will require latexpdf installed)
make          # list all the available output format

All the outputs will be in the docs folder (for html: docs/html). Note that there will be a folder for every tag or branch that is being built by sphinx-multiversion, as well as a redirect page at the root to automatically redirect to the main branch build.

without pipenv/virtualenv

Requirements (system):

• make

Requirements (Python 3):

• sphinx
• pydata-sphinx-theme=="0.13.3"

After installing the requirements you can run:

make html     # for html
make latex    # for latex
make latexpdf # for latex (will require latexpdf installed)
make          # list all the available output format

Sphinx Multiversion Extension

The sphinx-multiversion extension is used to automate the build for all tags and the main branch of these docs. This allows a dropdown menu to be placed in the left sidebar where the user can choose which version of the docs they want to browse. This dropdown menu is governed by the 'source/_templates/versioning.html' file, and can be modified via HTML/CSS to any theme or visualization.

Note that this extension is not building the uncommitted files in the current working directory; it is building the files that have been committed to the branch locally. This means that you must commit all files locally before building if you want to preview the pages. Additionally, if your local branches (i.e., main) are not up to date, your local preview may not reflect the most recent changes to the repo.

To view more than just the tags and the main branch, be sure to add a whitelist.txt file at the top level of the repo according to the instructions above, providing the name of the currently checked out branch. Ensure that all changes are committed locally as well before building the documentation, as it does not use the raw files but rather the git information for local and remote branches to build the pages.

For more information on the extension, and the different configuration options, check out their documentation site.