Merge branch 'fix-setup-py-description-and-release-doc-tweaks' into dev

jcfr · jcfr · commit a26db579c3b9 · 2017-11-11T09:29:15.000-05:00
* fix-setup-py-description-and-release-doc-tweaks:
  Makefile: Consolidate documentation targets, and add "htmlclean"
  docs: Fix duplicated label warnings in tutorials
  docs: Use consistent description between README and ReadTheDocs
  docs: Update "How to Update Requirements Files" section
  docs: Update external links offering https to use it
  setup.py: Set zip_safe to False to ensure installed package is never zipped.
  setup.py: Fix extraction and rendering of README.rst content
  setup.py: Fix presentation of package on PyPI by properly specifying license
  setup.py: Remove dead code and obsolete comments from setup.py
  docs: Fix "step-by-step" release process instructions
diff --git a/Makefile b/Makefile
@@ -39,19 +39,20 @@ test_docker:
 
 apidoc:
 	cd docs && $(MAKE) apidoc
-	@echo ""
-	@echo "To view the PDF documentation open: docs/_build/html/index.html"
 
-htmldoc:
+htmldoc-only: apidoc
 	cd docs && $(MAKE) html
-	@echo ""
-	@echo "To view the PDF documentation open: docs/_build/html/index.html"
 
-docs-only: htmldoc
+htmlclean:
+	cd docs && $(MAKE) clean
 
-docs: docs-only
+htmldoc-open:
+	@echo ""
+	@echo "To view the HTML documentation open: docs/_build/html/index.html"
 	open docs/_build/html/index.html || xdg-open docs/_build/html/index.html
 
+htmldoc: htmldoc-only htmldoc-open
+
 pdfdoc:
 	cd docs && $(MAKE) latexpdf
 	@echo ""
diff --git a/README.rst b/README.rst
@@ -1,18 +1,20 @@
-===============================
-pynwb
-===============================
+=====
+PyNWB
+=====
 
-Documentation of PyNWB can be found at http://pynwb.readthedocs.io/.
+Documentation of PyNWB can be found at https://pynwb.readthedocs.io
 
 Build Status
 ------------
 
-+-----------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------+
-| Linux                                                                                   | macOS                                                                                   | Windows                                                                               |
-+=========================================================================================+=========================================================================================+=======================================================================================+
-| .. image:: https://circleci.com/gh/NeurodataWithoutBorders/pynwb.svg?style=shield       | .. image:: https://travis-ci.org/NeurodataWithoutBorders/pynwb.svg?branch=dev           | .. image:: https://ci.appveyor.com/api/projects/status/9y808ua44yldy5n3?svg=true      |
-|     :target: https://circleci.com/gh/NeurodataWithoutBorders/pynwb                      |     :target: https://travis-ci.org/NeurodataWithoutBorders/pynwb                        |     :target: https://ci.appveyor.com/project/NeurodataWithoutBorders/pynwb            |
-+-----------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------+
+.. table::
+
+  +-----------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------+
+  | Linux                                                                                   | macOS                                                                                   | Windows                                                                               |
+  +=========================================================================================+=========================================================================================+=======================================================================================+
+  | .. image:: https://circleci.com/gh/NeurodataWithoutBorders/pynwb.svg?style=shield       | .. image:: https://travis-ci.org/NeurodataWithoutBorders/pynwb.svg?branch=dev           | .. image:: https://ci.appveyor.com/api/projects/status/9y808ua44yldy5n3?svg=true      |
+  |     :target: https://circleci.com/gh/NeurodataWithoutBorders/pynwb                      |     :target: https://travis-ci.org/NeurodataWithoutBorders/pynwb                        |     :target: https://ci.appveyor.com/project/NeurodataWithoutBorders/pynwb            |
+  +-----------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+---------------------------------------------------------------------------------------+
 
 
 Overall Health
@@ -28,9 +30,17 @@ Overall Health
 NWB Format API
 ==============
 
-A Python API for working with Neurodata stored in the NWB Format
+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 <https://nwb-schema.readthedocs.io>`_.
+
+`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.
 
--`Learn more <http://www.nwb.org/>`_.
+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.
 
 Code of Conduct
 ===============
diff --git a/docs/source/example.rst b/docs/source/example.rst
@@ -469,14 +469,14 @@ Create a new namespace with extensions
     Using the API to generate extensions (rather than writing YAML sources directly) helps avoid errors in the specification
     (e.g., due to missing required keys or invalid values) and ensure compliance of the extension definition with the
     NWB specification language. It also helps with maintanence of extensions, e.g., if extensions have to be ported to
-    newer versions of the `specification language <http://schema-language.readthedocs.io/en/latest/>`_
+    newer versions of the `specification language <https://schema-language.readthedocs.io/en/latest/>`_
     in the future.
 
 
 Documenting Extensions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Using the same tools used to generate the documentation for the `NWB-N core format <http://nwb-schema.readthedocs.io/en/latest/>`_
+Using the same tools used to generate the documentation for the `NWB-N core format <https://nwb-schema.readthedocs.io/en/latest/>`_
 one can easily generate documentation in HTML, PDF, ePub and many other format for extensions as well.
 
 For the purpose of this example we assume that our current directory has the following structure.
@@ -559,7 +559,7 @@ Further Reading
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 * **Using Extensions:** See :ref:`useextension` for an example on how to use extensions during read and write.
-* **Specification Language:** For a detailed overview of the specification language itself see http://schema-language.readthedocs.io/en/latest/
+* **Specification Language:** For a detailed overview of the specification language itself see https://schema-language.readthedocs.io/en/latest/
 
 Validating NWB files
 -----------------------------------------------------
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -7,7 +7,7 @@ NWB for Python
 ==============
 
 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>`_.
+efficiently working with Neurodata stored in the `NWB format <https://nwb-schema.readthedocs.io>`_.
 
 `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
diff --git a/docs/source/make_a_release.rst b/docs/source/make_a_release.rst
@@ -76,14 +76,14 @@ Step-by-step
 
 2. Download latest sources::
 
-    $ cd /tmp && git clone git@github.com:NeurodataWithoutBorders/pynwb
+    $ cd /tmp && git clone git@github.com:NeurodataWithoutBorders/pynwb && cd pynwb
 
 
 3. Tag the release::
 
     $ git tag -s -m "pynwb ${release}" ${release} origin/dev
 
-    *Requires a GPG signing key*
+   *Requires a GPG signing key*
 
 
 4. Create a new virtual environment and install release requirements::
diff --git a/docs/source/overview.rst b/docs/source/overview.rst
@@ -26,7 +26,7 @@ Software Architecture
 NWB Format
 ==========
 
-The `NWB Format <http://nwb-schema.readthedocs.io>`_ is built around two concepts: *TimeSeries* and *Modules*.
+The `NWB Format <https://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.
diff --git a/docs/source/tutorial_source/convert.rst b/docs/source/tutorial_source/convert.rst
@@ -1,5 +1,3 @@
-.. _tutorial_convert:
-
 Converting data to NWB
 ======================
 
@@ -24,10 +22,10 @@ crcns-ret-1: Meister lab retina data
   stimuli.  Recordings were done by Yifeng Zhang in
   Markus Meister's lab at Harvard University in 2008.
   Further description of the data are available here:
-  http://crcns.org/data-sets/retina/ret-1/about-ret-1
+  https://crcns.org/data-sets/retina/ret-1/about-ret-1
 
 * **Data Terms of use** The data used on the notebook and, therefore also the NWB files generated by the notebook are governed
-  by the terms-of-use of CRCNS.org described here http://crcns.org/terms .
+  by the terms-of-use of CRCNS.org described here https://crcns.org/terms .
 
 * **Comparison to NWB 1.0.x`:**
 
diff --git a/docs/source/tutorial_source/extension.rst b/docs/source/tutorial_source/extension.rst
@@ -1,5 +1,3 @@
-.. _tutorial_extensions:
-
 Extensions
 =========================
 
diff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rst
@@ -2,5 +2,10 @@
 Tutorials
 #########
 
+..  _tutorial_convert:
+
 .. include:: tutorial_source/extension.rst
+
+..  _tutorial_extensions:
+
 .. include:: tutorial_source/convert.rst
diff --git a/docs/source/update_requirements.rst b/docs/source/update_requirements.rst
@@ -5,23 +5,57 @@
 How to Update Requirements Files
 ================================
 
-The different requirements files introduced in :ref:`software_process` are the following:
+The different requirements files introduced in :ref:`software_process` section are the following:
+
+* requirements.txt_
+* requirements-dev.txt_
+* requirements-doc.txt_
 
 .. _requirements.txt: https://github.com/NeurodataWithoutBorders/pynwb/blob/dev/requirements.txt
 .. _requirements-dev.txt: https://github.com/NeurodataWithoutBorders/pynwb/blob/dev/requirements-dev.txt
 .. _requirements-doc.txt: https://github.com/NeurodataWithoutBorders/pynwb/blob/dev/requirements-doc.txt
 
+requirements.txt
+================
+
+`Requirements.txt` of the project can be created or updated and then captured using
+the following script:
+
+.. code::
+
+   mkvirtualenv pynwb-requirements
+
+   cd pynwb
+   pip install .
+   pip freeze > requirements.txt
 
-section can be updated using
-These section explains how to update the multiple requirements files presented in the
+   deactivate
+   rmvirtualenv pynwb-requirements
 
 
+requirements-(dev|doc).txt
+==========================
 
-Requirements.txt of the project can be created and captured by following the code snippet below:
+Any of these requirements files can be updated updated using
+the following scripts:
 
 .. code::
 
    cd pynwb
-   mkvirtualenv pynwb
-   pip install .
-   pip freeze > requirements.txt
+
+   # Set the requirements file to update
+   target_requirements=requirements-dev.txt
+
+   mkvirtualenv pynwb-requirements
+
+   # Install updated requirements
+   pip install -U -r $target_requirements
+
+   # If relevant, you could pip install new requirements now
+   # pip install -U <name-of-new-requirement>
+
+   # Update list of pinned requirements
+   pip freeze > $target_requirements
+
+   deactivate
+   rmvirtualenv pynwb-requirements
diff --git a/setup.py b/setup.py
@@ -2,17 +2,10 @@
 
 from setuptools import setup, find_packages
 
-import os
 import versioneer
 
-schema_dir = '%s/src/pynwb/data' % os.path.abspath(os.path.dirname(__file__))
-
-with open('README.rst', 'rb') as f:
-    readme = str(f.read())
-
-with open('license.txt', 'rb') as f:
-    license = str(f.read())
-
+with open('README.rst', 'r') as fp:
+    readme = fp.read()
 
 pkgs = find_packages('src', exclude=['data'])
 print('found these packages:', pkgs)
@@ -25,10 +18,11 @@
     'cmdclass': versioneer.get_cmdclass(),
     'description': 'Package for working with Neurodata stored in the NWB format',
     'long_description': readme,
+    'long_description_content_type': 'text/x-rst; charset=UTF-8',
     'author': 'Andrew Tritt',
     'author_email': 'ajtritt@lbl.gov',
     'url': 'https://github.com/NeurodataWithoutBorders/pynwb',
-    'license': license,
+    'license': "BSD",
     'install_requires':
     [
         'numpy',
@@ -68,20 +62,8 @@
                 'NWB '
                 'NWB:N '
                 'NeurodataWithoutBorders',
-    # 'package_data': {'pynwb':["data/*.yaml"]},
-    # 'cmdclass':{
-    #    'build_py': CustomBuild,
-    # }
+    'zip_safe': False
 }
 
 if __name__ == '__main__':
-    '''
-    Do some stuff here to retrieve (download from centralized location, or parse
-    from a location in the repo directory) the schema. Once retrieved write to
-    to Python code somewhere. This could be pickling it, or writing it to a
-    Python file as an ecoded string. This way, modifying the schema will require
-    rebuilding the package, and the schema will be hardcoded.
-    '''
-
-    # get_schema()
     setup(**setup_args)

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,3 @@`
`1`		`-.. _tutorial_extensions:`
`2`		`-`
`3`	`1`	`Extensions`
`4`	`2`	`=========================`
`5`	`3`