From 0b2596db36ce1ed567b12e126612a51ba8897f94 Mon Sep 17 00:00:00 2001 From: Jean-Christophe Fillion-Robin Date: Sat, 11 Nov 2017 07:10:12 -0500 Subject: [PATCH 01/10] docs: Fix "step-by-step" release process instructions --- docs/source/make_a_release.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/make_a_release.rst b/docs/source/make_a_release.rst index 9367dbfa3..8ac4eaa6e 100644 --- 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:: From 391ddf0f5c796e71042bbe7c2061b85e8b5662f9 Mon Sep 17 00:00:00 2001 From: Jean-Christophe Fillion-Robin Date: Sat, 11 Nov 2017 07:30:07 -0500 Subject: [PATCH 02/10] setup.py: Remove dead code and obsolete comments from setup.py "schema_dir" variable was set twice. --- setup.py | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/setup.py b/setup.py index aa5323773..3eb4526df 100755 --- a/setup.py +++ b/setup.py @@ -2,11 +2,8 @@ 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()) @@ -68,20 +65,7 @@ 'NWB ' 'NWB:N ' 'NeurodataWithoutBorders', - # 'package_data': {'pynwb':["data/*.yaml"]}, - # 'cmdclass':{ - # 'build_py': CustomBuild, - # } } 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) From bf1eea0d9456676beae683bf5cb880f07214c3f7 Mon Sep 17 00:00:00 2001 From: Jean-Christophe Fillion-Robin Date: Sat, 11 Nov 2017 07:36:04 -0500 Subject: [PATCH 03/10] setup.py: Fix presentation of package on PyPI by properly specifying license This commit removes the reading of the license file and instead use the short identified matching what is already used in the "classifiers". --- setup.py | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/setup.py b/setup.py index 3eb4526df..cfadc2715 100755 --- a/setup.py +++ b/setup.py @@ -7,10 +7,6 @@ with open('README.rst', 'rb') as f: readme = str(f.read()) -with open('license.txt', 'rb') as f: - license = str(f.read()) - - pkgs = find_packages('src', exclude=['data']) print('found these packages:', pkgs) @@ -25,7 +21,7 @@ 'author': 'Andrew Tritt', 'author_email': 'ajtritt@lbl.gov', 'url': 'https://github.com/NeurodataWithoutBorders/pynwb', - 'license': license, + 'license': "BSD", 'install_requires': [ 'numpy', From 936a9ce10f45fb75d9d1318f0bd1ad3dd2840036 Mon Sep 17 00:00:00 2001 From: Jean-Christophe Fillion-Robin Date: Sat, 11 Nov 2017 08:05:05 -0500 Subject: [PATCH 04/10] setup.py: Fix extraction and rendering of README.rst content --- README.rst | 20 +++++++++++--------- setup.py | 5 +++-- 2 files changed, 14 insertions(+), 11 deletions(-) diff --git a/README.rst b/README.rst index ea4dea685..199a57995 100644 --- a/README.rst +++ b/README.rst @@ -1,18 +1,20 @@ -=============================== -pynwb -=============================== +===== +PyNWB +===== Documentation of PyNWB can be found at http://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 diff --git a/setup.py b/setup.py index cfadc2715..7d15b32cd 100755 --- a/setup.py +++ b/setup.py @@ -4,8 +4,8 @@ import versioneer -with open('README.rst', 'rb') as f: - readme = str(f.read()) +with open('README.rst', 'r') as fp: + readme = fp.read() pkgs = find_packages('src', exclude=['data']) print('found these packages:', pkgs) @@ -18,6 +18,7 @@ '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', From 5aeea09ce14c121a6c33dec0c94e97df2441d0eb Mon Sep 17 00:00:00 2001 From: Jean-Christophe Fillion-Robin Date: Sat, 11 Nov 2017 08:05:38 -0500 Subject: [PATCH 05/10] setup.py: Set zip_safe to False to ensure installed package is never zipped. --- setup.py | 1 + 1 file changed, 1 insertion(+) diff --git a/setup.py b/setup.py index 7d15b32cd..9eb77da55 100755 --- a/setup.py +++ b/setup.py @@ -62,6 +62,7 @@ 'NWB ' 'NWB:N ' 'NeurodataWithoutBorders', + 'zip_safe': False } if __name__ == '__main__': From 2135496c27220bb19ed5079d1879f196cb0d1562 Mon Sep 17 00:00:00 2001 From: Jean-Christophe Fillion-Robin Date: Sat, 11 Nov 2017 08:27:27 -0500 Subject: [PATCH 06/10] docs: Update external links offering https to use it --- README.rst | 2 +- docs/source/example.rst | 6 +++--- docs/source/index.rst | 2 +- docs/source/overview.rst | 2 +- docs/source/tutorial_source/convert.rst | 4 ++-- 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/README.rst b/README.rst index 199a57995..ebf5ceae6 100644 --- a/README.rst +++ b/README.rst @@ -2,7 +2,7 @@ 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 ------------ diff --git a/docs/source/example.rst b/docs/source/example.rst index becc000b1..19e6c53ca 100644 --- 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 `_ + newer versions of the `specification language `_ in the future. Documenting Extensions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Using the same tools used to generate the documentation for the `NWB-N core format `_ +Using the same tools used to generate the documentation for the `NWB-N core format `_ 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 index 193917b7b..027b49712 100644 --- 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 `_. +efficiently working with Neurodata stored in the `NWB format `_. `Neurodata Without Borders: Neurophysiology (NWB:N) `_ is a project to develop a unified data format for cellular-based neurophysiology data, focused on the diff --git a/docs/source/overview.rst b/docs/source/overview.rst index 389f55166..fb8bea6a5 100644 --- a/docs/source/overview.rst +++ b/docs/source/overview.rst @@ -26,7 +26,7 @@ Software Architecture NWB Format ========== -The `NWB Format `_ is built around two concepts: *TimeSeries* and *Modules*. +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. diff --git a/docs/source/tutorial_source/convert.rst b/docs/source/tutorial_source/convert.rst index 6577393aa..8d02abcca 100644 --- a/docs/source/tutorial_source/convert.rst +++ b/docs/source/tutorial_source/convert.rst @@ -24,10 +24,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`:** From ef33b066df09ecc0012b1185062fee202229f0c8 Mon Sep 17 00:00:00 2001 From: Jean-Christophe Fillion-Robin Date: Sat, 11 Nov 2017 08:55:00 -0500 Subject: [PATCH 07/10] docs: Update "How to Update Requirements Files" section --- docs/source/update_requirements.rst | 48 ++++++++++++++++++++++++----- 1 file changed, 41 insertions(+), 7 deletions(-) diff --git a/docs/source/update_requirements.rst b/docs/source/update_requirements.rst index 44a034454..9b2445196 100644 --- 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 \ No newline at end of file + + # 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 + + # Update list of pinned requirements + pip freeze > $target_requirements + + deactivate + rmvirtualenv pynwb-requirements From 7010dc4fe9ed68a44aa0452ae040c8c4091136e0 Mon Sep 17 00:00:00 2001 From: Jean-Christophe Fillion-Robin Date: Sat, 11 Nov 2017 09:03:02 -0500 Subject: [PATCH 08/10] docs: Use consistent description between README and ReadTheDocs --- README.rst | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index ebf5ceae6..309375a15 100644 --- a/README.rst +++ b/README.rst @@ -30,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 `_. --`Learn more `_. +`Neurodata Without Borders: Neurophysiology (NWB:N) `_ 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 +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 =============== From b17bbdf89d83dd0d975c2db8b1f7a616ff246db4 Mon Sep 17 00:00:00 2001 From: Jean-Christophe Fillion-Robin Date: Sat, 11 Nov 2017 09:25:18 -0500 Subject: [PATCH 09/10] docs: Fix duplicated label warnings in tutorials source/tutorial_source/convert.rst:4: WARNING: duplicate label tutorial_convert, other instance in /home/jcfr/Projects/pynwb/docs/source/tutorial_source/convert.rst source/tutorial_source/extension.rst:4: WARNING: duplicate label tutorial_extensions, other instance in /home/jcfr/Projects/pynwb/docs/source/tutorial_source/extension.rst --- docs/source/tutorial_source/convert.rst | 2 -- docs/source/tutorial_source/extension.rst | 2 -- docs/source/tutorials.rst | 5 +++++ 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/source/tutorial_source/convert.rst b/docs/source/tutorial_source/convert.rst index 8d02abcca..5a4d2255b 100644 --- a/docs/source/tutorial_source/convert.rst +++ b/docs/source/tutorial_source/convert.rst @@ -1,5 +1,3 @@ -.. _tutorial_convert: - Converting data to NWB ====================== diff --git a/docs/source/tutorial_source/extension.rst b/docs/source/tutorial_source/extension.rst index 7da77d463..efcd06ac5 100644 --- 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 index 83e1498ad..4badce57c 100644 --- 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 From 5b65cdf924e9f89079c7ea106e609b7529c627ae Mon Sep 17 00:00:00 2001 From: Jean-Christophe Fillion-Robin Date: Sat, 11 Nov 2017 09:28:53 -0500 Subject: [PATCH 10/10] Makefile: Consolidate documentation targets, and add "htmlclean" * removed docs and docs-only targets * apidoc : generate apidoc * htmldoc-only : build apidoc, build html * htmldoc : build apidoc, build html and open in browser * htmlclean : remove documentation build artifacts --- Makefile | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/Makefile b/Makefile index 28c4cd493..09a70b1e9 100644 --- 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 ""