Documentation

We use Sphinx for DrumScript documentation. We use the Shibuya Sphinx theme for layout.

DrumScript documentation structure

See here and below

DrumScript Documentation Structure
==================================

This folder contains the source files for the DrumScript Sphinx documentation website.

Key Folders:
------------
/guide          -> User-focused tutorials (Installation, Usage).
/theory         -> Explanations, Background Science, and Notation Guides.
    /images     -> PNG/JPG assets for theory pages.
/development    -> Guides for code contributors (Testing, Code of Conduct).
/release_notes  -> Documentation related to `DrumScript` releases.
/_static        -> Website assets (Logos, Custom CSS).
/_build         -> The output folder (Generated HTML lives here).

Key Files:
----------
index.md        -> The Homepage (Table of Contents).
conf.py         -> Sphinx Configuration (Theme, Plugins).
api.rst         -> Auto-generated Python API Reference.

Setup your development environment

  1. Clone DrumScript repo

  2. Use git checkout -b feature/update_sphinx_docs. Github will switch you to the feature/update_sphinx_docs branch. NOTE: feature/update_sphinx_docs is indicative of branch name. Please always use a subfolder, ie build/, 2.1.x/, feature/ etc depending on your changes

  3. Use git push origin -u feature/update_sphinx_docs to publish your branch to the remote origin

  4. Activate .venv using source .venv/bin/activate, then type uv pip install -e ".[dev]" to install the sphinx packages

You can deactivate your .venv anytime from the root folder of DrumScript using deactivate

  1. Start making changes. Once you push a change, raise a PR. CODEOWNERS will automatically be assigned to review once the PR is ready for review.

About testing the documentation

Always test local rendering before submitting changes for review in your PR.

There are three main files that we use to amend the Sphinx documentation:

  1. docs/conf.py: Configures the Shibuya theme. Use this to define how Sphinx builds the layout, amend navbar links.

  2. docs/index.md: Sets up the structure of the documentation/ subfolders

  3. docs/api.rst: Recursively obtains functions and arguments to post under API reference on the documentation

Images are stored in docs/_static.

How to re-build the documentation

  1. cd docs

  2. rm -rf _build

  3. make html: a short way of executing the full command python -m sphinx -b html -d _build/doctrees . _build/html. Check the output in your Terminal to verify the build and scan for errors.

Render locally (opens in browser)

  1. Ensure you are in the root directory (DrumScript/)

  2. open docs/_build/html/index.html

  3. Once you are happy, commit the changes.