Skip to main content

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

Project description

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

PyPI - License PyPI Build Status

Overview

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

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

To cite this tool use: (HDMF Documentation Utilities, RRID:SCR_021341)

Installation

pip install hdmf-docutils

Available Tools

  • hdmf_generate_format_docs: Generate figures and RST documents from the HDMF YAML specification for the format specification documentation. Previously called “nwb_generate_format_docs”.

  • hdmf_init_sphinx_extension_doc: Create format specification SPHINX documentation for an HDMF extension. Previously called “nwb_init_sphinx_extension_doc”.

  • hdmf_gallery_prototype: Tool for prototyping sphinx gallery examples. Previously called “nwb_gallery_prototype”.

Available Modules

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

Available Notebooks

History

nwb-docutils was renamed to hdmf-docutils and generalized to be (mostly) independent of NWB in January, 2020.

nwb-docutils 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.

Usage

pip install hdmf-docutils

For the purpose of this example, we assume that our current directory has the following structure.

- my_extension/
  - my_extension_source/
      - mylab.namespace.yaml
      - mylab.specs.yaml
      - ...
      - docs/  (Optional)
          - mylab_description.rst
          - mylab_release_notes.rst

In addition to Python 3.x, you will also need sphinx (including the sphinx-quickstart tool) installed. Sphinx is available here http://www.sphinx-doc.org/en/stable/install.html .

We can now create the sources of our documentation as follows:

   python3 hdmf_init_sphinx_extension_doc  \
                --project my-extension \
                --author "Dr. Master Expert" \
                --version "1.2.3" \
                --release alpha \
                --output my_extension_docs \
                --spec_dir my_extension_source \
                --namespace_filename mylab.namespace.yaml \
                --default_namespace mylab
                --external_description my_extension_source/docs/mylab_description.rst \  (Optional)
                --external_release_notes my_extension_source/docs/mylab_release_notes.rst \  (Optional)

.. tip::

   Additional instructions for how to use and customize the extension documentations are also available
   in the ``Readme.md`` file that  ``init_sphinx_extension_doc.py`` automatically adds to the docs.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hdmf_docutils-0.4.5.tar.gz (1.6 MB view details)

Uploaded Source

Built Distribution

hdmf_docutils-0.4.5-py2.py3-none-any.whl (1.6 MB view details)

Uploaded Python 2 Python 3

File details

Details for the file hdmf_docutils-0.4.5.tar.gz.

File metadata

  • Download URL: hdmf_docutils-0.4.5.tar.gz
  • Upload date:
  • Size: 1.6 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.4

File hashes

Hashes for hdmf_docutils-0.4.5.tar.gz
Algorithm Hash digest
SHA256 b238d1a7e1d39dcd125caab89c00e0da5ffb52c6045e7c1aa14cd6d14320e753
MD5 1cbd1fec7f05c39d972183a3b97e81b6
BLAKE2b-256 c654bb2102b787b75a91dfb4aedd5100dd26c39124b1f8c7a7eb85f053963c84

See more details on using hashes here.

File details

Details for the file hdmf_docutils-0.4.5-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for hdmf_docutils-0.4.5-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 26367ea63f4cf5ae44e23e11cd03a8b21aecf0f5c88364ce94758d84081f6d2f
MD5 11a1b4923600c7c8026db7e3ca13e087
BLAKE2b-256 f9a2db1d332f19c123a97dedcf705dfc8f1e6a06e4a338be70950ef8c3c9e0c7

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page