diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e3aa27b --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +# Sphinx documentation +_build/ diff --git a/LICENSE b/LICENSE deleted file mode 100644 index baa1838..0000000 --- a/LICENSE +++ /dev/null @@ -1,29 +0,0 @@ -BSD 3-Clause License - -Copyright (c) 2020, Hierarchical Data Modeling Framework -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -1. Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - -2. Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -3. Neither the name of the copyright holder nor the names of its - contributors may be used to endorse or promote products derived from - this software without specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/Legal.txt b/Legal.txt new file mode 100644 index 0000000..178ee82 --- /dev/null +++ b/Legal.txt @@ -0,0 +1,5 @@ +“hdmf” Copyright (c) 2020, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from the U.S. Dept. of Energy). All rights reserved. + +If you have questions about your rights to use or distribute this software, please contact Berkeley Lab's Innovation & Partnerships Office at IPO@lbl.gov. + +NOTICE. This Software was developed under funding from the U.S. Department of Energy and the U.S. Government consequently retains certain rights. As such, the U.S. Government has been granted for itself and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide license in the Software to reproduce, distribute copies to the public, prepare derivative works, and perform publicly and display publicly, and to permit other to do so. diff --git a/Makefile b/Makefile index d4db539..02a319e 100644 --- a/Makefile +++ b/Makefile @@ -7,14 +7,13 @@ SPHINXBUILD = sphinx-build SPHINXAPIDOC = sphinx-apidoc PAPER = BUILDDIR = _build -SRCDIR = ../src RSTDIR = source PKGNAME = hdmf-schema-language # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(RSTDIR) # the i18n builder cannot share the environment and doctrees with the others I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . @@ -44,9 +43,10 @@ help: @echo " changes to make an overview of all changed/added/deprecated items" @echo " linkcheck to check all external links for integrity" @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " clean to clean all documents built by Sphinx in _build" clean: - -rm -rf $(BUILDDIR)/* $(RSTDIR)/$(PKGNAME)* $(RSTDIR)/modules.rst + -rm -rf $(BUILDDIR)/* html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html diff --git a/Readme.md b/Readme.md index f976728..559b2e6 100644 --- a/Readme.md +++ b/Readme.md @@ -1,25 +1,40 @@ -**Overview** +# Overview -The HDMF specification documentation uses Sphinx [http://www.sphinx-doc.org/en/stable/index.html](http://www.sphinx-doc.org/en/stable/index.html) +The HDMF specification language defines formal structures for describing the organization of complex data using basic +concepts, e.g., Groups, Datasets, Attributes, and Links. See the +[documentation](http://hdmf-schema-language.readthedocs.io/) for more information and release notes. -**Building the documentation** +The HDMF specification language is used by the +[Hierarchical Data Modeling Framework (HDMF)](https://github.com/hdmf-dev/hdmf). -To build the documentation simply: +## For maintainers -```make ``` +The HDMF specification documentation is generated using [Sphinx](http://www.sphinx-doc.org/en/stable/index.html) -where `````` is, e.g., ```latexpdf```, ```html```, ```singlehtml``` or ```man```. For a complete list of supported doc-types see: +### Building the documentation -```make help``` +Install the latest version of [Sphinx](http://www.sphinx-doc.org/en/stable/index.html): +``` +python -m pip install sphinx +``` -**Cleaning up** +To build the documentation, enter: +``` +make +``` +where `` is, e.g., `html`, `latexpdf`. -By calling: +For a complete list of supported doc-types, enter: +``` +make help +``` -```make clean``` - - - -. +To remove previously generated documentation, enter: +``` +make clean +``` +### Making a release +1. Update the release notes in `source/release_notes.rst`. +2. Update the version in `source/namespace_map.yml`, `source/hdmf.schema.json`, and `source/conf.py` diff --git a/license.txt b/license.txt new file mode 100644 index 0000000..db3fbac --- /dev/null +++ b/license.txt @@ -0,0 +1,13 @@ +“hdmf” Copyright (c) 2020, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from the U.S. Dept. of Energy). All rights reserved. + +Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: + +(1) Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. + +(2) Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. + +(3) Neither the name of the University of California, Lawrence Berkeley National Laboratory, U.S. Dept. of Energy nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +You are under no obligation whatsoever to provide any bug fixes, patches, or upgrades to the features, functionality or performance of the source code ("Enhancements") to anyone; however, if you choose to make your Enhancements available either publicly, or directly to Lawrence Berkeley National Laboratory, without imposing a separate written license agreement for such Enhancements, then you hereby grant the following license: a non-exclusive, royalty-free perpetual license to install, use, modify, prepare derivative works, incorporate into other computer software, distribute, and sublicense such enhancements or derivative works thereof, in binary and source code form. diff --git a/make.bat b/make.bat index deed45a..d17cd94 100644 --- a/make.bat +++ b/make.bat @@ -6,7 +6,8 @@ if "%SPHINXBUILD%" == "" ( set SPHINXBUILD=sphinx-build ) set BUILDDIR=_build -set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . +set RSTDIR=source +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% %RSTDIR% set I18NSPHINXOPTS=%SPHINXOPTS% . if NOT "%PAPER%" == "" ( set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% @@ -18,6 +19,7 @@ if "%1" == "" goto help if "%1" == "help" ( :help echo.Please use `make ^` where ^ is one of + echo. fulldoc to rebuild the apidoc, html, and latex documents all at once echo. html to make standalone HTML files echo. dirhtml to make HTML files named index.html in directories echo. singlehtml to make a single large HTML file @@ -35,6 +37,8 @@ if "%1" == "help" ( echo. changes to make an overview over all changed/added/deprecated items echo. linkcheck to check all external links for integrity echo. doctest to run all doctests embedded in the documentation if enabled + echo. apidoc to build RST from source code + echo. clean to clean all documents built by Sphinx in _build goto end ) @@ -187,4 +191,13 @@ results in %BUILDDIR%/doctest/output.txt. goto end ) +if "%1" == "fulldoc" ( + make clean + echo. + echo.Rebuilding html, latexpdf + make html + make latex + goto end +) + :end diff --git a/source/conf.py b/source/conf.py index c4e7277..d28a436 100644 --- a/source/conf.py +++ b/source/conf.py @@ -11,7 +11,7 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import sys, os +#import sys, os import sphinx_rtd_theme from ruamel import yaml from jinja2 import Template @@ -51,16 +51,16 @@ # General information about the project. project = u'HDMF Specification Language' -copyright = u'2020, Neurodata Without Borders' +copyright = u'2020, The Regents of the University of California, through Lawrence Berkeley National Laboratory' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = 'v2.0.0' +version = 'v2.1.0-beta' # The full version, including alpha/beta/rc tags. -release = 'v2.0.0-beta' +release = version # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -120,8 +120,8 @@ def rstjinja(app, docname, source): def setup(app): - app.add_stylesheet("theme_overrides.css") # overrides for wide tables in RTD theme - app.connect("source-read", rstjinja) + app.add_css_file("theme_overrides.css") # overrides for wide tables in RTD theme + app.connect("source-read", rstjinja) # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/source/credits.rst b/source/credits.rst index c093338..f9f561d 100644 --- a/source/credits.rst +++ b/source/credits.rst @@ -5,26 +5,17 @@ Credits Acknowledgments =============== -For details on the partners, members, and supporters of NWB:N please the http://www.nwb.org/ project website. -For specific contributions to the format specification and this document see the change logs. +The HDMF schema language was ported from the `schema language +`_ used by the Neurodata Without Borders (NWB) +neurophysiology data standardization project. NWB now uses the HDMF schema language with some different key names. Authors ======= -NWB:N: Version 2.0.0 and later ------------------------------- - -Documentation for Version 2 of the NWB:N specification and later have been created by -Oliver Ruebel and Andrew Tritt et al. in collaboration with the NWB:N community. - -NWB:N: Version 1.0.x and earlier --------------------------------- - -The specification language and corresponding documentation for Version 1.0.5g (and earlier) -of the NWB file format were created by Jeff Teeters et al. as -part of the first NWB pilot project. The documents for NWB:N 2 have been adopted from the -final version of format docs released by the original NWB pilot project. - +- Ben Dichter +- Ryan Ly +- Oliver Ruebel +- Andrew Tritt ***** Legal @@ -33,10 +24,9 @@ Legal Copyright ========= -.. include:: ../../../Legal.txt +.. include:: ../Legal.txt -Licence +License ======= -.. include:: ../../../license.txt - +.. include:: ../license.txt diff --git a/source/specification_language_description.rst b/source/description.rst similarity index 99% rename from source/specification_language_description.rst rename to source/description.rst index 53c155e..d6c6980 100644 --- a/source/specification_language_description.rst +++ b/source/description.rst @@ -1,10 +1,12 @@ .. _specification_language: -************************** +******************************************* {{ spec_format }} Specification Language -************************** +******************************************* -Version: |release| |today| [1]_ +Version: |release| [1]_ + +Last modified: |today| Introduction ============ @@ -89,7 +91,7 @@ Namespaces Namespaces are used to define a collections of specifications, to enable users to develop extensions in their own namespace and, hence, to avoid -name/type collisions. Namespaces are defined in seperate YAML files. +name/type collisions. Namespaces are defined in separate YAML files. The specification of a namespace looks as follows: .. code-block:: python @@ -956,11 +958,6 @@ Relationships implicit relationships encoded via shared dimension descriptions and implicit references in datasets in previous versions of the specification language. - - .. [1] The version number given here is for the specification language and - is independent of the version number for the NWB format. The date - after the version number is the last modification date of this - document. - + is independent of the version number for the specification itself. diff --git a/source/hdmf.schema.json b/source/hdmf.schema.json index ba0f756..17d9cae 100644 --- a/source/hdmf.schema.json +++ b/source/hdmf.schema.json @@ -3,7 +3,7 @@ "$id": "hdmf.schema.json", "title": "Schema for the HDMF language specification", "description": "A schema for validating HDMF YAML files and HDMF extensions", - "version": "2.0.2", + "version": "2.1.0-beta", "type": "object", "additionalProperties": false, "properties": { diff --git a/source/index.rst b/source/index.rst index 4908f4b..ab86afc 100644 --- a/source/index.rst +++ b/source/index.rst @@ -1,21 +1,16 @@ -Welcome to the {{ spec_format }} Specification Language -========================================= +The {{ spec_format }} Specification Language +============================================================================== +The HDMF specification language defines formal structures for describing the organization of complex data using basic +concepts, e.g., Groups, Datasets, Attributes, and Links. -.. toctree:: - :numbered: - :maxdepth: 6 - :caption: Table of Contents - - specification_language_description - specification_language_release_notes - credits - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +See the full language description, release notes, and credits below. +.. toctree:: + :numbered: + :maxdepth: 6 + :caption: Table of Contents + description + release_notes + credits diff --git a/source/namespace_map.yml b/source/namespace_map.yml index 0147940..458ff14 100644 --- a/source/namespace_map.yml +++ b/source/namespace_map.yml @@ -3,4 +3,4 @@ data_type_inc: data_type_inc data_type_def: data_type_def data_types: data_types api: hdmf -version: '2.0.0b' +version: '2.1.0-beta' diff --git a/source/specification_language_release_notes.rst b/source/release_notes.rst similarity index 91% rename from source/specification_language_release_notes.rst rename to source/release_notes.rst index f84ccec..2335990 100644 --- a/source/specification_language_release_notes.rst +++ b/source/release_notes.rst @@ -2,8 +2,12 @@ Release Notes ============= -Version 2.0.2 (Upcoming) -------------------------- +Version 2.1.0 (Upcoming) +--------------------------------- +* First release as hdmf-schema-language. + +Version 2.0.2 (March, 2020) +--------------------------------- * add ``value`` and ``default_value`` as optional keys of a dataset. * ``dtype`` changed from required to optional for datasets. @@ -12,7 +16,6 @@ Version 2.0.1 (March, 2019) * Added support for specifying a ``title`` and ``doc`` for ``source`` files as part of the ``schema`` portion of a ``namespace`` specification. This was added to improve documentation of individual source files and to support sorting of types by source file with meaningful titles and text as part of autogenerated docs. * Updated the docs for ``quantity`` to indicate that the default value is ``1`` if not specified. - Version 2.0.0 (January, 2019) ---------------------------------- @@ -127,17 +130,13 @@ allows us to express the same concepts in an easier-to-use fashion. Accordingly, the keys ```include```, ```merge``` and ```merge+``` have been removed in version 1.2a. Here a summary of the basic cases: -+--------------------+--------------------+------------------------------------------------------------------------+ -| data_type_inc | data_type_def | Description | -+====================+====================+========================================================================+ -|not set | not set | define standard dataset or group without a type | -+--------------------+--------------------+------------------------------------------------------------------------+ -|not set | set | create a new data_type from scratch | -+--------------------+--------------------+------------------------------------------------------------------------+ -|set | not set | include (reuse) data_type without creating a new one (include) | -+--------------------+--------------------+------------------------------------------------------------------------+ -|set | set | merge/extend data_type and create a new type (merge) | -+--------------------+--------------------+------------------------------------------------------------------------+ +.. csv-table:: + :header: ``{{ data_type_inc }}``, ``{{ data_type_def }}``, Description + + not set, not set, define a standard dataset or group without a type + not set, set, create a new data_type from scratch + set, not set, include (reuse) data_type without creating a new one (include) + set, set, merge/extend data_type and create a new type (inheritance/merge) ```structured_dimensions``` ^^^^^^^^^^^^^^^^^^^^^^^^^^^