hdmf-docutils 0.4.7

概述

本项目是一个用于生成HDMF文档的有用的CLIs、脚本和模块集合。

使用hdmf-docutils生成扩展的文档： http://pynwb.readthedocs.io/en/latest/extensions.html#documenting-extensions

引用此工具时使用： (HDMF文档工具，RRID:SCR_021341)

安装

pip install hdmf-docutils

可用工具

• hdmf_generate_format_docs：从HDMF YAML规范生成格式规范文档的图形和RST文档。之前称为“nwb_generate_format_docs”。

• hdmf_init_sphinx_extension_doc：为HDMF扩展创建格式规范SPHINX文档。之前称为“nwb_init_sphinx_extension_doc”。

• hdmf_gallery_prototype：用于原型化sphinx gallery示例的工具。之前称为“nwb_gallery_prototype”。

可用模块

• hdmf_docutils/doctools/*：此包包含用于生成HDMF文件和规范层次结构的图形以及帮助程序生成reStructuredText (RST)文档的模块。

可用笔记本

• compare-hdf5-files.ipynb：此笔记本演示了如何比较hdf5文件。

历史

nwb-docutils于2020年1月更名为hdmf-docutils，并扩展为（主要是）独立于NWB。

nwb-docutils最初是nwb-schema项目的子目录。对应的历史记录在第4届NWB黑客马拉松期间提取出来，成为一个专门的pip安装项目，以方便核心NWB文档项目和各种NWB扩展使用。

用法

pip install hdmf-docutils

为此示例的目的，我们假设我们的当前目录具有以下结构。

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

除了Python 3.x之外，您还需要安装sphinx（包括sphinx-quickstart工具）。Sphinx可在此处获得 https://sphinx-doc.cn/en/stable/install.html .

现在我们可以创建我们的文档源如下

   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.