Merge branch '235-reorganize-doc-sections' into dev

jcfr · jcfr · commit 18830e2dfe42 · 2017-11-11T06:57:02.000-05:00
* 235-reorganize-doc-sections:
  docs: Re-organize and improve documentation.
  docs: Fix import of pynwb in "conf.py"
  Makefile: Add convenient target "docs" and "docs-only"
  gitignore: Exclude auto-generated apidocs RST files
diff --git a/.gitignore b/.gitignore
@@ -7,8 +7,13 @@
 .history
 
 ### PyNWB###
+
 docs/notebooks/boc/
 
+# Auto-generated apidocs RST files
+docs/source/pynwb*.rst
+docs/source/modules.rst
+
 ### Python ###
 # Byte-compiled / optimized / DLL files
 __pycache__/
diff --git a/Makefile b/Makefile
@@ -47,6 +47,11 @@ htmldoc:
 	@echo ""
 	@echo "To view the PDF documentation open: docs/_build/html/index.html"
 
+docs-only: htmldoc
+
+docs: docs-only
+	open docs/_build/html/index.html || xdg-open docs/_build/html/index.html
+
 pdfdoc:
 	cd docs && $(MAKE) latexpdf
 	@echo ""
diff --git a/README.rst b/README.rst
@@ -26,24 +26,24 @@ Overall Health
      :alt: Requirements Status
 
 NWB Format API
-========================
+==============
 
 A Python API for working with Neurodata stored in the NWB Format
 
 -`Learn more <http://www.nwb.org/>`_.
 
 Code of Conduct
-=======================
+===============
 
 This project and everyone participating in it is governed by our `code of conduct guidelines <docs/CODE_OF_CONDUCT.rst>`_ . By participating, you are expected to uphold this code.
 
 Contributing
-=======================
+============
 
 For details on how to contribute to PyNWB see our `contribution guidelines <docs/CONTRIBUTING.rst>`_ .
 
 LICENSE
-=======================
+=======
 
 "pynwb" Copyright (c) 2017, 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:
@@ -59,7 +59,7 @@ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 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.
 
 COPYRIGHT
-=======================
+=========
 
 "pynwb" Copyright (c) 2017, 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 ce at  IPO@lbl.gov.
diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -16,7 +16,7 @@
 import os
 import sphinx_rtd_theme
 from sphinx.domains.python import PythonDomain
-from .pynwb._version import get_versions
+from pynwb._version import get_versions
 
 
 # If extensions (or modules to document with autodoc) are in another directory,
diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst
@@ -0,0 +1 @@
+.. include:: ../CONTRIBUTING.rst
diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst
@@ -1,9 +1,5 @@
 ..  _getting_started:
 
-===============
-Getting Started
-===============
-
 ------------
 Dependencies
 ------------
@@ -13,15 +9,14 @@ PyNWB has the following minimum requirements, which must be installed before you
 #. Python 2.7 or Python 3.6
 #. pip
 
-The NWB format provides a formal specification for storing neurophysiology data in HDF5. HDF5 provides support
-for parallel I/O using MPI-IO, and therefore requires MPI.
-
 ------------
 Installation
 ------------
 
-Install from pypi
------------------
+Install release from PyPI
+-------------------------
+
+The `Python Package Index (PyPI) <https://pypi.org>`_ is a repository of software for the Python programming language.
 
 To install or update PyNWB distribution from PyPI simply run:
 
@@ -38,20 +33,24 @@ This will automatically install the following required dependencies:
  #. ruamel.yaml
  #. six
 
-Install latest dev version
---------------------------
 
-.. note::
+Install latest pre-release
+--------------------------
 
-  This is useful to tryout the latest features and also setup automatic build of your
-  own project against the latest version of pynwb.
+This is useful to tryout the latest features and also setup continuous integration of your
+own project against the latest version of PyNWB.
 
 .. code::
 
-   $ pip install pynwb --find-links https://github.com/NeurodataWithoutBorders/pynwb/releases/tag/latest  --no-index
+   $ pip install -U pynwb --find-links https://github.com/NeurodataWithoutBorders/pynwb/releases/tag/latest  --no-index
+
 
-Install from Git repository (for development)
----------------------------------------------
+--------------
+For developers
+--------------
+
+Install from Git repository
+---------------------------
 
 For development an editable install is recommended.
 
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -4,24 +4,31 @@
    contain the root `toctree` directive.
 
 NWB for Python
-=================================
+==============
 
-PyNWB is a Python package for working with NWB files.
+PyNWB is a Python package for working with NWB files. It provides a high-level API for
+efficiently working with Neurodata stored in the `NWB format <http://nwb-schema.readthedocs.io>`_.
 
-Neurodata Without Borders: Neurophysiology (NWB:N) is a project to develop a
+`Neurodata Without Borders: Neurophysiology (NWB:N) <http://www.nwb.org/>`_ is a project to develop a
 unified data format for cellular-based neurophysiology data, focused on the
 dynamics of groups of neurons measured under a large range of experimental
-conditions. The NWB:N team consists of neuroscientists and software developers
+conditions.
+
+The NWB:N team consists of neuroscientists and software developers
 who recognize that adoption of a unified data format is an important step toward
 breaking down the barriers to data sharing in neuroscience.
 
 .. toctree::
    :maxdepth: 2
-   :caption: Basics
+   :caption: Getting Started
 
    getting_started
-   architecture
-   software_process
+   contributing
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Overview
+
    overview
 
 .. toctree::
@@ -31,12 +38,14 @@ breaking down the barriers to data sharing in neuroscience.
    example
    tutorials
    api_docs
+   software_process
 
 .. toctree::
    :maxdepth: 2
-   :caption: Maintainer
+   :caption: For Maintainers
 
    make_a_release
+   update_requirements
 
 .. toctree::
    :maxdepth: 2
diff --git a/docs/source/make_a_release.rst b/docs/source/make_a_release.rst
@@ -22,9 +22,9 @@ Prerequisites
 
 * You have the API key associated with `<https://github.com/nwb-bot>`_.
 
-----------
-Convention
-----------
+-------------------------
+Documentation conventions
+-------------------------
 
 The commands reported below should be evaluated in the same terminal session.
 
@@ -133,7 +133,7 @@ Step-by-step
 
 8. Upload the packages to the production PyPI server::
 
-    $ twine upload dist/*
+    $ twine upload --sign dist/*
 
   .. warning::
 
diff --git a/docs/source/overview.rst b/docs/source/overview.rst
@@ -1,27 +1,50 @@
 .. _overview:
 
-Overview
-===============
+Introduction
+============
 
 PyNWB provides a high-level Python API for reading and writing NWB formatted HDF5 files. This section will provide
 a broad overview of the functionality provided for reading and writing neurophysiology data into NWB files.
 
 
-The NWB format is built around two concepts: *TimeSeries* and *Modules*. :ref:`timeseries_overview` are objects for storing time series
-data, and :ref:`modules_overview` are objects for storing and grouping analyses. The following sections describe these classes in further detail.
+.. _software-architecture:
+
+Software Architecture
+=====================
+
+.. _fig-software-architecture:
+
+.. figure:: figures/software_architecture.*
+   :scale: 100 %
+   :alt: PyNWB Software Architecture
+
+   Overview of the high-level software architecture of PyNWB.
+
+
+.. _nwb_format_overview:
+
+NWB Format
+==========
+
+The `NWB Format <http://nwb-schema.readthedocs.io>`_ is built around two concepts: *TimeSeries* and *Modules*.
+
+:ref:`timeseries_overview` are objects for storing time series data, and :ref:`modules_overview` are objects
+for storing and grouping analyses. The following sections describe these classes in further detail.
+
 
 .. _file_overview:
 
 NWBFile
----------------
+=======
 
-NWB files are represented in PyNWB with *NWBFile* objects. :py:class:`~pynwb.file.NWBFile` objects provide functionality for creating :ref:`timeseries_overview` datasets
-and :ref:`modules_overview`, as well as functionality for storing experimental metadata and other metadata related to data provenance.
+NWB files are represented in PyNWB with *NWBFile* objects. :py:class:`~pynwb.file.NWBFile` objects provide functionality
+for creating :ref:`timeseries_overview` datasets and :ref:`modules_overview`, as well as functionality for storing
+experimental metadata and other metadata related to data provenance.
 
 .. _timeseries_overview:
 
 TimeSeries
----------------
+----------
 
 TimeSeries objects store time series data. These Python objects correspond to TimeSeries specifications
 provided by the NWB format specification. Like the NWB specification, TimeSeries Python objects follow an object-oriented inheritance
@@ -64,7 +87,7 @@ The following TimeSeries objects are provided by the API and NWB specification:
 .. _modules_overview:
 
 Modules
----------------
+-------
 
 Modules are objects that group together common analyses done during processing of data. Module objects are unique collections of
 analysis results. To standardize the storage of common analyses, NWB provides the concept of an *Interface*, where the output of
diff --git a/docs/source/software_process.rst b/docs/source/software_process.rst
@@ -17,51 +17,52 @@ The project has both unit and integration tests.
 
 Each time a PR is published or updated, the project is built, packaged and tested on all support operating systems and python distributions. That way, as a contributor you know if you introduced regressions or coding style inconsistencies.
 
-There are badges in the readme_ file which shows the current condition of the dev branch.
+There are badges in the README_ file which shows the current condition of the dev branch.
+
+.. _README: https://github.com/NeurodataWithoutBorders/pynwb#readme
 
-.. _readme: https://github.com/NeurodataWithoutBorders/pynwb/blob/dev/README.rst
 
 --------
 Coverage
 --------
 
-Coverage is computed and reported using the coverage_ tool. There is a badge in the readme file which
+Coverage is computed and reported using the coverage_ tool. There is a badge in the README_ file which
 shows percentage coverage. A detailed report can be found on codecov_ which shows line by line which
 lines are covered by the tests.
 
 .. _coverage: https://coverage.readthedocs.io
 .. _codecov: https://codecov.io/gh/NeurodataWithoutBorders/pynwb/tree/dev/src/pynwb
 
-------------
-Requirements
-------------
+..  _software_process_requirement_specifications:
+
 
-There are 2 kinds of requirements specification in PyNWB. The first one is the dependencies_
-in the setup.py file which lists the abstract dependencies for the PyNWB project.
-Note that there should not be specific versions of packages in the setup.py file.
+--------------------------
+Requirement Specifications
+--------------------------
 
-.. _dependencies: https://github.com/NeurodataWithoutBorders/pynwb/blob/dev/setup.py#L32-L40
+There are 2 kinds of requirements specification in PyNWB.
 
-requirements.txt_ file on the other hand lists pinned (concrete) dependencies to reproduce an entire development
-environment to work with PyNWB. That is why specific versions are pinned in the requirements.txt.
+Setup.py Dependencies
+---------------------
 
-.. _requirements.txt: https://github.com/NeurodataWithoutBorders/pynwb/blob/dev/requirements.txt
+The first one is the dependencies_ in the `setup.py` file which lists the abstract dependencies for
+the PyNWB project. Note that there should not be specific versions of packages in the `setup.py` file.
 
-Requirements.txt of the project can be created and captured by following the code snippet below:
+Requirements.txt Dependencies
+-----------------------------
 
-.. code::
+The second one is `requirements.txt` which contain a list of pinned (concrete) dependencies to reproduce
+an entire development environment to work with PyNWB.
 
-   cd pynwb
-   mkvirtualenv pynwb
-   pip install .
-   pip freeze > requirements.txt
+In order to check the status of the required packages requires.io_ is used to create a badge on the project
+README_. If all the required packages are up to date,
+a green badge appears.
 
-In order to check the status of the required packages requires.io_ is used.
+If some of the packages are outdated, see :ref:`update_requirements_files`.
 
+.. _dependencies: https://github.com/NeurodataWithoutBorders/pynwb/blob/dev/setup.py
 .. _requires.io: https://requires.io/github/NeurodataWithoutBorders/pynwb/requirements/?branch=dev
 
-Requires.io also creates a badge on the project readme. If all the required packages are up to date,
-a green badge will appear.
 
 -------------------------
 Versioning and Releasing
diff --git a/docs/source/tutorial_source/convert.rst b/docs/source/tutorial_source/convert.rst
@@ -1,7 +1,7 @@
 .. _tutorial_convert:
 
-Convert
-=========================
+Converting data to NWB
+======================
 
 The following are example Jupyter notebooks for converting custom lab data to NWB:
 
diff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rst
@@ -1,6 +1,6 @@
 
 Tutorials
-#################################
+#########
 
 .. include:: tutorial_source/extension.rst
 .. include:: tutorial_source/convert.rst
diff --git a/docs/source/update_requirements.rst b/docs/source/update_requirements.rst
