nwb-docutils 0.3.0

Collection of CLIs, scripts and modules useful to generate the NWB documentation

This project is under active development. Its content, API and behavior may change at any time. We mean it.

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