Neurobagel Documentation

The neurobagel documentation.

Our docs are built with the Material Theme for MKdocs.

Setup

Create a new virtual environment with python -m venv venv and activate it. Then install the dependencies with pip install -r requirements.txt

Adding new pages to the navigation

We use mkdocs-awesome-nav to define the navigation structure of the docs.

To add a new page, add it to the .nav.yml (structured the same way as the nav section of mkdocs.yml) of the directory the markdown file lives in.

To add an entire subdirectory (section) of pages, you can simply specify the subdirectory name, e.g.:

  - User guide: user_guide

Each subdirectory can then itself contain a .nav.yml to organize the pages within.

Note: Both relative and absolute paths can be used to specify files or directories in .nav.yml.

Updating the environment variables reference

The environment variables reference is auto-rendered from the file docs/includes/environment_variables.yaml using a macro stored in docs/macros/main.py.

To update the metadata for a variable, directly edit the source yaml file.

To update the formatting of the rendered markdown reference sections, edit the macro functions inside the macro module directly.

Variable ordering: The order of variable sections is defined in the macro module. For a given ini_section, variables appear in the order they are defined in the yaml file.

Information on excluding markdown sections or pages from macro rendering can be found here.

Build

To spin up the site locally while you edit it, run:

mkdocs serve

More details are in the mkdocs documentation.

Deploy

At the moment we are using mkdocs to deploy directly to gh-pages.

When your local build runs well, commit the changes to the main branch with a PR and then call

mkdocs gh-deploy

See the docs for more details.

Installing tailwind

To install tailwind, run:

npm i

Rebuilding tailwind

If you need to rebuild the tailwind css, run:

npx tailwindcss build docs/stylesheets/tailwind.css -o docs/stylesheets/output.css

Style guide

We use several tools in this repository to enforce our style guide (codespell, prettier, markdownlint...). They can all be run in an orchestrated manner using pre-commit python package.

You can install pre-commit by doing:

pip install pre-commit
pre-commit install

After this the style guide will be enforced every time you commit: some pre-commit 'hooks' will try to fix some of the errors they find, so you may have to restage your file before committing.

For markdownlint, you can also use the VS-code extension to flag (and sometimes autofix) potential formatting errors in your markdown file.