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 "" diff --git a/README.rst b/README.rst index ea4dea685..309375a15 100644 --- 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 `_. + +`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. --`Learn more `_. +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 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/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:: 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..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 ====================== @@ -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 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 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 diff --git a/setup.py b/setup.py index aa5323773..9eb77da55 100755 --- 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)