Overview

This project is a collection of CLIs, scripts and modules useful to generate the NWB documentation.

Using nwb-docutils to generate documentation for an extension: http://pynwb.readthedocs.io/en/latest/extensions.html#documenting-extensions

Installation

pip install nwb-docutils

Available Tools

• nwb_generate_format_docs: Generate figures and RST documents from the NWB YAML specification for the format specification documentation.

• nwb_init_sphinx_extension_doc: Create format specification SPHINX documentation for an NWB extension.

• nwb_gallery_prototype

Available Modules

• nwb_docutils/doctools/*: This package contains modules used to generate figures of the hierarchies of NWB-N files and specifications as well as to help with the programmatic generation of reStructuredText (RST) documents.

Available Notebooks

• compare-hdf5-files.ipynb: This notebook illustrates how to compare hdf5 files.

History

nwb-utils was initially a sub-directory of the nwb-schema project. Corresponding history was extracted during the 4th NWB Hackathon into a dedicated pip-installable project to facilitate its use by both core NWB documentation projects and various NWB extensions.

maintainers: how to make a release ?

1. Configure ~/.pypirc as described here.

2. Make sure the cli and module work as expected.

3. List all tags sorted by version

   $ git fetch --tags && \
     git tag -l | sort -V

4. Choose the next release version number:

   release="X.Y.Z"

5. Tag the release. Requires a GPG key with signatures

   git tag -s -m "nwb-docutils ${release}" ${release} origin/master

   And push

   git push origin ${release}

6. Create the source tarball and binary wheels

   rm -rf dist/
   python setup.py sdist bdist_wheel

7. Upload the packages to the testing PyPI instance

   twine upload --sign -r pypitest dist/*

8. Check the PyPI testing package page.

9. Upload the packages to the PyPI instance:

   twine upload --sign dist/*

10. Check the PyPI package page.

11. Create a virtual env, and make sure the package can be installed

    mkvirtualenv test-nwb-docutils-install
    pip install nwb-docutils

12. Cleanup

    deactivate
    rmvirtualenv test-nwb-docutils-install