Project setup
#############

Environment
***********

..  code-block:: bash
    
    # 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
********

..  code-block:: python
    :caption: 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
********

.. code-block:: bash

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