Project setup

Environment

# setup working environment
# it might be useful to use one common
# environment for all projects

$ python3 -m venv .venv
$ source .venv/bin/activate
$ pip install sphinx sphinx sphinx-rtd-theme sphinx-tags sphinx-toolbox
$ sphinx-quickstart

Settings

source/conf.py

extensions =
    "sphinx.ext.todo",
    "sphinx_tags",
    "sphinx_rtd_theme",
    "sphinx_toolbox.collapse",
    "volca_patch", # if installed in source/_ext
    "chordlyrics" # if installed in source/_ext
    ]

html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']

tags_create_tags = True
todo_include_todos = True

html_theme_options = {
        'collapse_navigation': False,
        'sticky_navigation': True,
        'navigation_depth': 4,
        'titles_only': False,
        }

def setup(app):
    app.add_css_file("chords.css") # will include source/static/chords.css

Todo

Explain custom directives

Workflow

$ make html
$ pip install sphinx-autobuild
$ sphinx-autobuild  source build