Refactor and reorganize repo contents, update version to 2.1.0 (#2)

Add .gitignore
Add Legal.txt and license.txt from HDMF, remove LICENSE
Update make.bat and Makefile
Rename and update README.md
Update source/conf.py
Update source/credits.rst
Add friendlier introduction to source/index.rst
Fix formatting in various RST docs
Update version throughout to 2.1.0

.gitignore

@@ -0,0 +1,2 @@
+# Sphinx documentation
+_build/

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 [email protected].
+
+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.

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

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 <doctype>```
+The HDMF specification documentation is generated using [Sphinx](http://www.sphinx-doc.org/en/stable/index.html)
 
-where ```<doctype>``` 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 <doctype>
+```
+where `<doctype>` 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`

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.

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 ^<target^>` where ^<target^> 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

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

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
+<https://schema-language.readthedocs.io/en/latest/>`_ 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

source/specification_language_description.rst → 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.

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": {

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

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'

source/specification_language_release_notes.rst → 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```
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^