Fix documentation; use hdmf-docutils (#388)

* Fix formatting errors

* Use hdmf-docutils and hdmf-common-schema

* Link to stable not latest hdmf-common-schema

Author: rly

docs/format/Makefile

@@ -170,7 +170,7 @@ doctest:
 	      "results in $(BUILDDIR)/doctest/output.txt."
 
 apidoc:
-	PYTHONPATH=$(CONFDIR):$(PYTHONPATH) nwb_generate_format_docs
+	PYTHONPATH=$(CONFDIR):$(PYTHONPATH) hdmf_generate_format_docs
 	@echo
 	@echo "Generate rst source files from NWB spec."
 

docs/format/Readme.md

@@ -4,7 +4,7 @@ The NWB:N specification documentation uses Sphinx [http://www.sphinx-doc.org/en/
 
 **Prerequisites**
 
-```pip install nwb-docutils```
+```pip install hdmf-docutils```
 
 **Rebuilding All**
 
@@ -27,7 +27,7 @@ The format documentation is auto-generated from the format specification (YAML/J
 
 ```make apidoc```
 
-This will invoke the ``nwb_generate_format_docs`` executable provided by ``nwb-docutils`` package to automatically generate a series of .rst, .png, and .pdf files that are stored in the folder ```source/_format_auto_docs```. The generated .rst files are included in ```source/format.rst``` and the png and pdf files are used as figures in the autogenerated docs. The folder ```source/format_auto_docs``` is reserved for autogenerated files, i.e., files in the folder should not be added or edited by hand as they will be deleted and rebuilt during the full build of the documentation.
+This will invoke the ``hdmf_generate_format_docs`` executable provided by ``hdmf-docutils`` package to automatically generate a series of .rst, .png, and .pdf files that are stored in the folder ```source/_format_auto_docs```. The generated .rst files are included in ```source/format.rst``` and the png and pdf files are used as figures in the autogenerated docs. The folder ```source/format_auto_docs``` is reserved for autogenerated files, i.e., files in the folder should not be added or edited by hand as they will be deleted and rebuilt during the full build of the documentation.
 
 By default the Sphinx configuration is setup to always regenerate the sources whenever the docs are being built (see next section). This behavior can be customized via the ```spec_doc_rebuild_always``` parameter in ```source/conf.py```
 
@@ -85,7 +85,7 @@ Finally, the name and location of output files can be customized as follows:
 * ```spec_output_src_filename```  Name of the file where the sources of the format spec go. NOTE: This file is only generated if spec_generate_src_file is enabled
 * ```spec_output_doc_type_hierarchy_filename```  Name of the file containing the type hierarchy. (Included in spec_output_doc_filename)
 
-To speed up the build of the format docs we can prevent the ``nwb_generate_format_docs`` executable from regenerating the sources from YAML if the git-hash from the previous build is still current. This is controlled via the following options:
+To speed up the build of the format docs we can prevent the ``hdmf_generate_format_docs`` executable from regenerating the sources from YAML if the git-hash from the previous build is still current. This is controlled via the following options:
 
 * ``spec_clean_output_dir_if_old_git_hash`` Clean up the output directory before we generate the source if the git hash is out of date
 

docs/format/make.bat

@@ -204,7 +204,7 @@ results in %BUILDDIR%/doctest/output.txt.
 
 if "%1" == "apidoc" (
   set PYTHONPATH=%cd%/source;%PYTHONPATH%
-	nwb_generate_format_docs
+	hdmf_generate_format_docs
 	if errorlevel 1 exit /b 1
 	echo.
 	echo.Generate rst source files from NWB spec.

docs/format/source/conf.py

@@ -31,7 +31,7 @@ def run_doc_autogen(_):
    from conf_doc_autogen import spec_output_dir
 
    if spec_doc_rebuild_always or not os.path.exists(spec_output_dir):
-      from nwb_docutils.generate_format_docs import main as generate_docs
+      from hdmf_docutils.generate_format_docs import main as generate_docs
       generate_docs()
 
 def setup(app):
@@ -59,7 +59,7 @@ def setup(app):
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -121,6 +121,10 @@ def setup(app):
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
 
+intersphinx_mapping = {
+    'hdmf-common-schema': ('https://hdmf-common-schema.readthedocs.io/en/stable/', None),
+}
+
 
 # -- Options for HTML output ---------------------------------------------------
 

docs/format/source/format_description.rst

@@ -211,12 +211,12 @@ All NWB:N Groups and Datasets with an assigned neurodata_type have three require
 
 - ``neurodata_type`` (variable-length string) is the name of the NWB:N primitive that this group or dataset maps onto
 - ``namespace`` (variable-length string) is the namespace where ``neurodata_type`` is defined, e.g. "core" or the
-namespace of an extension
+  namespace of an extension
 - ``object_id`` (variable-length string) is a universally unique identifier for this object within its hierarchy.
-It should be set to the string representation of a random UUID version 4 value
-(see `RFC 4122 <https://tools.ietf.org/html/rfc4122>`_) upon first creation. It is **not** a hash of the data. Files
-that contain the exact same data but were generated in different instances will have different ``object_id`` values.
-Currently, modification of an object does not require its ``object_id`` to be changed.
+  It should be set to the string representation of a random UUID version 4 value
+  (see `RFC 4122 <https://tools.ietf.org/html/rfc4122>`_) upon first creation. It is **not** a hash of the data. Files
+  that contain the exact same data but were generated in different instances will have different ``object_id`` values.
+  Currently, modification of an object does not require its ``object_id`` to be changed.
 
 
 

docs/format/source/format_release_notes.rst

@@ -2,7 +2,7 @@ Release Notes
 =============
 
 2.2.0 (January 6, 2020)
-----------------
+-----------------------
 
 - Moved common data structures such as Container and DynamicTable to hdmf-common-schema.
 

docs/language/source/specification_language_description.rst

@@ -64,12 +64,12 @@ and subsequent sections.
 
 .. tip::
 
-    The ``nwb-docutils`` package includes tools to generate Sphinx documentation from
-    format specifications. In particular the executable ``nwb_init_sphinx_extension_doc``
+    The ``hdmf-docutils`` package includes tools to generate Sphinx documentation from
+    format specifications. In particular the executable ``hdmf_init_sphinx_extension_doc``
     provides functionality to setup documentation for a format or extension defined
     by a namespace (similar to the documentation for NWB core namespace at http://nwb-schema.readthedocs.io/en/latest/ ).
-    Use ``nwb_init_sphinx_extension_doc --help`` to view the list
-    of options for generating the docs. The package also includes the executable ``nwb_generate_format_docs``
+    Use ``hdmf_init_sphinx_extension_doc --help`` to view the list
+    of options for generating the docs. The package also includes the executable ``hdmf_generate_format_docs``
     which is used for generating actual reStructuredText files and figures from YAML/JSON
     specification sources. For an example see: http://pynwb.readthedocs.io/en/latest/example.html#documenting-extensions
 

requirements-doc.txt

@@ -1 +1,2 @@
-nwb-docutils
+hdmf-docutils
+pynwb