============================
HDMF Documentation Utilities
============================
*This project is under active development. Its content, API and behavior may change at any time. We mean it.*
.. image:: https://img.shields.io/pypi/l/hdmf-docutils.svg
:target: https://github.com/hdmf-dev/hdmf-docutils/blob/master/license.txt
:alt: PyPI - License
.. image:: https://img.shields.io/pypi/v/hdmf-docutils.svg
:target: https://pypi.org/project/hdmf-docutils/
:alt: PyPI
.. image:: https://dev.azure.com/hdmf-dev/hdmf-docutils/_apis/build/status/hdmf-dev.hdmf-docutils?branchName=master
:target: https://dev.azure.com/hdmf-dev/hdmf-docutils/_build/latest?definitionId=1&branchName=master
:alt: 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
-------------------
* `compare-hdf5-files.ipynb <https://github.com/hdmf-dev/hdmf-docutils/blob/master/hdmf_docutils/compare-hdf5-files.ipynb>`_: This
notebook illustrates how to compare hdf5 files.
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 <https://neurodatawithoutborders.github.io/nwb_hackathons/HCK04_2018_Seattle/>`_ into a
dedicated *pip-installable* project to facilitate its use by both core NWB documentation projects and various
NWB extensions.
Usage
-----
.. code-block:: text
pip install hdmf-docutils
For the purpose of this example, we assume that our current directory has the following structure.
.. code-block:: text
- 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:
.. code-block:: text
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.
.. tip::
See ``make help`` for a list of available options for building the documentation in many different
output formats (e.g., PDF, ePub, LaTeX, etc.).
.. tip::
See ``python3 init_sphinx_extension_doc.py --help`` for a complete list of option to customize the documentation
directly during initialization.
.. tip::
The above example included additional description and release note docs as part of the specification. These are
included in the docs via ``.. include`` commands so that changes in those files are automatically picked up
when rebuilding to docs. Alternatively, we can also add custom documentation directly to the docs.
In this case the options ``--custom_description format_description.rst``
and ``--custom_release_notes format_release_notes.rst`` of the ``init_sphinx_extension_doc.py`` script are useful
to automatically generate the basic setup for those files so that one can easily start to add content directly
without having to worry about the additional setup.
Raw data
{
"_id": null,
"home_page": "https://github.com/hdmf-dev/hdmf-docutils",
"name": "hdmf-docutils",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "Neuroscience python HDF HDF5 cross-platform open-data data-format open-source open-science reproducible-research NWB NWB:N NeurodataWithoutBorders",
"author": "Oliver Ruebel",
"author_email": "oruebel@lbl.gov",
"download_url": "https://files.pythonhosted.org/packages/9f/1b/f158126022295c963102b19a0ab0a0f7644c0df7af05b3c4adb8aaeb0b53/hdmf_docutils-0.4.7.tar.gz",
"platform": null,
"description": "============================\nHDMF Documentation Utilities\n============================\n\n*This project is under active development. Its content, API and behavior may change at any time. We mean it.*\n\n.. image:: https://img.shields.io/pypi/l/hdmf-docutils.svg\n :target: https://github.com/hdmf-dev/hdmf-docutils/blob/master/license.txt\n :alt: PyPI - License\n\n.. image:: https://img.shields.io/pypi/v/hdmf-docutils.svg\n :target: https://pypi.org/project/hdmf-docutils/\n :alt: PyPI\n\n.. image:: https://dev.azure.com/hdmf-dev/hdmf-docutils/_apis/build/status/hdmf-dev.hdmf-docutils?branchName=master\n :target: https://dev.azure.com/hdmf-dev/hdmf-docutils/_build/latest?definitionId=1&branchName=master\n :alt: Build Status\n\nOverview\n--------\n\nThis project is a collection of CLIs, scripts and modules useful to generate the HDMF documentation.\n\nUsing hdmf-docutils to generate documentation for an extension: http://pynwb.readthedocs.io/en/latest/extensions.html#documenting-extensions\n\nTo cite this tool use: (HDMF Documentation Utilities, RRID:SCR_021341)\n\n\nInstallation\n------------\n\n::\n\n pip install hdmf-docutils\n\n\n\nAvailable Tools\n---------------\n\n* ``hdmf_generate_format_docs``: Generate figures and RST documents from the HDMF YAML specification for the\n format specification documentation. Previously called \"nwb_generate_format_docs\".\n\n* ``hdmf_init_sphinx_extension_doc``: Create format specification SPHINX documentation for an HDMF extension.\n Previously called \"nwb_init_sphinx_extension_doc\".\n\n* ``hdmf_gallery_prototype``: Tool for prototyping sphinx gallery examples. Previously called \"nwb_gallery_prototype\".\n\n\nAvailable Modules\n-----------------\n\n* ``hdmf_docutils/doctools/*``: This package contains modules used to generate figures of the hierarchies of\n HDMF files and specifications as well as to help with the programmatic generation of reStructuredText (RST)\n documents.\n\n\nAvailable Notebooks\n-------------------\n\n* `compare-hdf5-files.ipynb <https://github.com/hdmf-dev/hdmf-docutils/blob/master/hdmf_docutils/compare-hdf5-files.ipynb>`_: This\n notebook illustrates how to compare hdf5 files.\n\n\nHistory\n-------\n\nnwb-docutils was renamed to hdmf-docutils and generalized to be (mostly) independent of NWB in January, 2020.\n\nnwb-docutils was initially a sub-directory of the nwb-schema project. Corresponding history was extracted during\nthe `4th NWB Hackathon <https://neurodatawithoutborders.github.io/nwb_hackathons/HCK04_2018_Seattle/>`_ into a\ndedicated *pip-installable* project to facilitate its use by both core NWB documentation projects and various\nNWB extensions.\n\nUsage\n-----\n\n.. code-block:: text\n\n pip install hdmf-docutils\n\nFor the purpose of this example, we assume that our current directory has the following structure.\n\n\n.. code-block:: text\n\n - my_extension/\n - my_extension_source/\n - mylab.namespace.yaml\n - mylab.specs.yaml\n - ...\n - docs/ (Optional)\n - mylab_description.rst\n - mylab_release_notes.rst\n\nIn addition to Python 3.x, you will also need ``sphinx`` (including the ``sphinx-quickstart`` tool) installed.\nSphinx is available here http://www.sphinx-doc.org/en/stable/install.html .\n\nWe can now create the sources of our documentation as follows:\n\n.. code-block:: text\n\n python3 hdmf_init_sphinx_extension_doc \\\n --project my-extension \\\n --author \"Dr. Master Expert\" \\\n --version \"1.2.3\" \\\n --release alpha \\\n --output my_extension_docs \\\n --spec_dir my_extension_source \\\n --namespace_filename mylab.namespace.yaml \\\n --default_namespace mylab\n --external_description my_extension_source/docs/mylab_description.rst \\ (Optional)\n --external_release_notes my_extension_source/docs/mylab_release_notes.rst \\ (Optional)\n \n .. tip::\n\n Additional instructions for how to use and customize the extension documentations are also available\n in the ``Readme.md`` file that ``init_sphinx_extension_doc.py`` automatically adds to the docs.\n\n.. tip::\n\n See ``make help`` for a list of available options for building the documentation in many different\n output formats (e.g., PDF, ePub, LaTeX, etc.).\n\n.. tip::\n\n See ``python3 init_sphinx_extension_doc.py --help`` for a complete list of option to customize the documentation\n directly during initialization.\n\n.. tip::\n\n The above example included additional description and release note docs as part of the specification. These are\n included in the docs via ``.. include`` commands so that changes in those files are automatically picked up\n when rebuilding to docs. Alternatively, we can also add custom documentation directly to the docs.\n In this case the options ``--custom_description format_description.rst``\n and ``--custom_release_notes format_release_notes.rst`` of the ``init_sphinx_extension_doc.py`` script are useful\n to automatically generate the basic setup for those files so that one can easily start to add content directly\n without having to worry about the additional setup.\n\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Collection of CLIs, scripts and modules useful to generate the NWB documentation",
"version": "0.4.7",
"project_urls": {
"Homepage": "https://github.com/hdmf-dev/hdmf-docutils"
},
"split_keywords": [
"neuroscience",
"python",
"hdf",
"hdf5",
"cross-platform",
"open-data",
"data-format",
"open-source",
"open-science",
"reproducible-research",
"nwb",
"nwb:n",
"neurodatawithoutborders"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "12438a45ca662bfbd60e78e3eb6bbcb836ee781183a79bf483bcd7b4c5af51cd",
"md5": "260901d10dca9ad1eb7167e4ceae7323",
"sha256": "c16ab9c125b473679358c05605bc85ec0026bcfcd1735cac49b7b5ff7a478d5b"
},
"downloads": -1,
"filename": "hdmf_docutils-0.4.7-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "260901d10dca9ad1eb7167e4ceae7323",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 1601707,
"upload_time": "2024-03-31T07:04:59",
"upload_time_iso_8601": "2024-03-31T07:04:59.639615Z",
"url": "https://files.pythonhosted.org/packages/12/43/8a45ca662bfbd60e78e3eb6bbcb836ee781183a79bf483bcd7b4c5af51cd/hdmf_docutils-0.4.7-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9f1bf158126022295c963102b19a0ab0a0f7644c0df7af05b3c4adb8aaeb0b53",
"md5": "da26af9f1bbe66671932c1c9a4a5d85c",
"sha256": "5902e4310c07ce4a5d116ebf0a60491f6659c0528a41461da36dc54d440ebafe"
},
"downloads": -1,
"filename": "hdmf_docutils-0.4.7.tar.gz",
"has_sig": false,
"md5_digest": "da26af9f1bbe66671932c1c9a4a5d85c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 1620080,
"upload_time": "2024-03-31T07:05:02",
"upload_time_iso_8601": "2024-03-31T07:05:02.466055Z",
"url": "https://files.pythonhosted.org/packages/9f/1b/f158126022295c963102b19a0ab0a0f7644c0df7af05b3c4adb8aaeb0b53/hdmf_docutils-0.4.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-31 07:05:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hdmf-dev",
"github_project": "hdmf-docutils",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hdmf-docutils"
}
JSON
