Documentation Guide

Developers Guide to BMTK Documentation

2024 Refactor

1. Get the branch for documentation refactor

For the full bmtk document refactor please use the refactor/documentation branch in the BMTK repo.

You can create a clone just for the bmtk documentation with the following command (consider forking the branch first):

  $ git clone -b refactor/documentation https://github.com/AllenInstitute/bmtk.git bmtk-doc-refactor

Once the new documentation is in a stable state and reaches up to the existing documentation I will merge it in and rebuild the web-page.

2. Compiling the Documentation

Installation Requirements

To rebuild the bmtk documentation you will need to have a Python 3.6+ environment with at minimum the following packages to create the html pages:

 $ pip install sphinx                # Package for generating documentation
 $ pip install numpydoc              # extension for compiling and displaying docstrings
 $ pip install nbsphinx jupyterlab   # extension for converting ipynb into html
 $ pip install sphinx-design         # extension for grids, cards, tabs, dropdowns, etc. 
 $ pip install pydata-sphinx-theme   # special theme/style

If you also want to fully compile the doc strings you will also need bmtk installed:

 $ pip install bmtk 
 $ pip install pytest 
 $ pip install neuron
 $ conda install -c conda-forge nest-simulator

Recompiling the documentation

You need to used the sphinx package to convert .rst and .ipynb files into .hmtl, build the doc strings, and format the css styles so that the web-pages can be read in a browser. From the bmtk repo home:

 $ cd docs/autodocs
 $ make html

It will proceed to compile the web-pages and (if successful) show a "The HTML pages are in build/html" message. The web-site pages will be saved to docs/autodocs/build/html/ folder and if you open docs/autodocs/build/html/index.html in a browser.

As you make changes use the make html and a local web-browser to view and verify them. Note: If you aren't seeing your changes or they aren't looking as expected (especially if you're seeing old removed files) try cleaning out the docs/autodocs/build/html/ folder using command

 $ make clean

(Next time you rerun it will rebuild entire web-site from scratch).

Updating the Documentation

• The main web pages are located in docs/autodocs/source primarily in .rst files - a type of markdown files. See sphinx documentation for working with these files.

• We also used the sphinx-design package which allows us to create special web-components like grids, cards, dropdowns, and tabs.

• Jupyter notebook tutorials are saved in docs/tutorials/ folder. When the sphinx docs are recompiled it will copy over these files automatically and compile them into html (see the copy_tutorials() function inside conf.py)

• Images and other non-html files should be saved in the docs/autodocs/source/_static/ folder.

• docs/autodocs/source/conf.py is the main file that sphinx uses when compiling the documentation; including determining what files to use, site metadata, themes, css, and other advanced features. When changing any global settings or special compilation instructions you can usually do so in the sphinx conf.py file.

• For more advanced styling and page changes to site that can't be modified in the conf.py file use docs/autodocs/source/_static/custom.css.