Merge branch 'dev' into rc/3.0.0

hdmf-dev · Jun 17, 2021 · 6e0c03d · 6e0c03d
2 parents b76fa73 + 929ec93
commit 6e0c03d
Show file tree

Hide file tree

Showing 14 changed files with 327 additions and 48 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -35,6 +35,21 @@
 -
 -
 
+## HDMF 2.5.8 (June 16, 2021)
+
+### Minor improvements
+- Improve Sphinx documentation. @rly (#627)
+
+### Bug fix
+- Fix error with representing an indexed table column when the `VectorIndex` dtype precision is upgraded more
+  than one step, e.g., uint8 to uint32. This can happen when, for example, a single `add_row` call is used to
+  add more than 65535 elements to an empty indexed column. @rly (#631)
+
+## HDMF 2.5.7 (June 4, 2021)
+
+### Bug fix
+- Fix generation of extension classes that extend `MultiContainerInterface` and use a custom _fieldsname. @rly (#626)
+
 ## HDMF 2.5.6 (May 19, 2021)
 
 ### Bug fix

diff --git a/docs/CONTRIBUTING.rst b/docs/CONTRIBUTING.rst
@@ -1,5 +1,5 @@
-How to contribute to HDMF software and documents
-=================================================
+Contributing Guide
+==================
 
 .. _sec-code-of-conduct:
 
@@ -87,32 +87,41 @@ From your local copy directory, use the following commands.
 Styleguides
 -----------
 
+Python Code Styleguide
+^^^^^^^^^^^^^^^^^^^^^^
+
+Before you create a Pull Request, make sure you are following the HDMF style guide (PEP8_).
+To check whether your code conforms to the HDMF style guide, simply run the flake8_ tool in the project's root
+directory.
+
+.. _flake8: http://flake8.pycqa.org/en/latest/
+.. _PEP8: https://www.python.org/dev/peps/pep-0008/
+
+.. code::
+
+   $ flake8
+
 Git Commit Message Styleguide
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 * Use the present tense ("Add feature" not "Added feature")
 * The first should be short and descriptive.
 * Additional details may be included in further paragraphs.
-* If a commit fixes an issues, then include "Fix #X" where X is the number of the issue.
+* If a commit fixes an issue, then include "Fix #X" where X is the number of the issue.
 * Reference relevant issues and pull requests liberally after the first line.
 
 Documentation Styleguide
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
 All documentations is written in reStructuredText (RST) using Sphinx.
 
-Python Code Styleguide
-^^^^^^^^^^^^^^^^^^^^^^
-
-Python coding style is checked via ``flake8`` for automatic checking of PEP8 style during pull requests.
-
 Endorsement
 -----------
 
 Please do not take working with an organization (e.g., during a hackathon or via GitHub) as an endorsement of your work or your organization. It's okay to say e.g., “We worked with XXXXX to advance science” but not e.g., “XXXXX supports our work on HDMF”.”
 
 License and Copyright
-=======================
+---------------------
 
 See the `license <https://raw.githubusercontent.com/hdmf-dev/hdmf/dev/license.txt>`_ files for details about the copyright and license.
 

diff --git a/docs/source/_static/theme_overrides.css b/docs/source/_static/theme_overrides.css
@@ -0,0 +1,7 @@
+.wy-side-nav-search .wy-dropdown>a.icon img.logo, .wy-side-nav-search>a.icon img.logo {
+  width: 150px;
+}
+
+.wy-nav-content {
+  max-width: 1000px !important;
+}
diff --git a/docs/source/building_api.rst b/docs/source/building_api.rst
@@ -1,4 +1,4 @@
-Building API classes
+Building API Classes
 ====================
 
 After you have written an extension, you will need a Pythonic way to interact with the data model. To do this,

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -175,7 +175,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ['_static']
+html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
@@ -325,5 +325,5 @@ def skip(app, what, name, obj, skip, options):
 
 def setup(app):
     app.connect('builder-inited', run_apidoc)
-    app.add_css_file("theme_overrides.css")  # overrides for wide tables in RTD theme
+    app.add_css_file("theme_overrides.css")
     app.connect("autodoc-skip-member", skip)
diff --git a/docs/source/extensions.rst b/docs/source/extensions.rst
@@ -1,6 +1,6 @@
 .. _extending-standard:
 
-Extending standards
+Extending Standards
 ===================
 
 The following page will discuss how to extend a standard using HDMF.

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,8 +1,3 @@
-.. HDMF documentation master file, created by
-   sphinx-quickstart on Thu Nov 17 10:41:07 2016.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 The Hierarchical Data Modeling Framework
 ========================================
 
@@ -17,55 +12,60 @@ with the intention of providing it as an open-source tool for other scientific c
 
 If you use HDMF in your research, please use the following citation:
 
-A. J. Tritt et al., "HDMF: Hierarchical Data Modeling Framework for Modern Science Data Standards,"
-2019 IEEE International Conference on Big Data (Big Data), Los Angeles, CA, USA, 2019, pp. 165-179,
-doi: 10.1109/BigData47090.2019.9005648.
+    A. J. Tritt et al., "HDMF: Hierarchical Data Modeling Framework for Modern Science Data Standards,"
+    2019 IEEE International Conference on Big Data (Big Data), Los Angeles, CA, USA, 2019, pp. 165-179,
+    doi: 10.1109/BigData47090.2019.9005648.
 
 
 .. toctree::
+   :hidden:
    :maxdepth: 2
    :caption: Getting Started
 
-   getting_started
-   contributing
+   install_users
+   tutorials/index
 
 .. toctree::
+   :hidden:
    :maxdepth: 2
    :caption: Overview
 
    overview_intro
    overview_software_architecture
    overview_citing
 
+
 .. toctree::
+   :hidden:
    :maxdepth: 2
    :caption: Resources
 
-   tutorials/index
+   api_docs
    extensions
    building_api
-   validation
    export
-   api_docs
-   software_process
+   validation
+
+.. toctree::
+   :hidden:
+   :caption: For Developers
+
+   install_developers
+   contributing
    make_roundtrip_test
+   software_process
 
 .. toctree::
+   :hidden:
    :maxdepth: 2
    :caption: For Maintainers
 
    make_a_release
    update_requirements
 
 .. toctree::
+   :hidden:
    :maxdepth: 2
    :caption: Legal
 
    legal
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
diff --git a/docs/source/install_developers.rst b/docs/source/install_developers.rst
@@ -0,0 +1,146 @@
+..  _install_developers:
+
+------------------------------
+Installing HDMF for Developers
+------------------------------
+
+Set up a virtual environment
+----------------------------
+
+For development, we recommend installing HDMF in a virtual environment in editable mode. You can use
+the virtualenv_ tool to create a new virtual environment. Or you can use the
+`conda package and environment management system`_ for managing virtual environments.
+
+.. _virtualenv: https://virtualenv.pypa.io/en/stable/
+.. _conda package and environment management system: https://conda.io/projects/conda/en/latest/index.html
+
+Option 1: Using virtualenv
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+First, install the latest version of the ``virtualenv`` tool and use it to create a new virtual environment. This
+virtual environment will be stored in the ``venv`` directory in the current directory.
+
+.. code:: bash
+
+    pip install -U virtualenv
+    virtualenv venv
+
+On macOS or Linux, run the following to activate your new virtual environment:
+
+.. code:: bash
+
+    source venv/bin/activate
+
+On Windows, run the following to activate your new virtual environment:
+
+.. code:: batch
+
+    venv\Scripts\activate
+
+This virtual environment is a space where you can install Python packages that are isolated from other virtual
+environments. This is especially useful when working on multiple Python projects that have different package
+requirements and for testing Python code with different sets of installed packages or versions of Python.
+
+Activate your newly created virtual environment using the above command whenever you want to work on HDMF. You can also
+deactivate it using the ``deactivate`` command to return to the base environment.
+
+Option 2: Using conda
+^^^^^^^^^^^^^^^^^^^^^
+
+First, install Anaconda_ to install the ``conda`` tool. Then create and
+activate a new virtual environment called "venv" with Python 3.8 installed.
+
+.. code:: bash
+
+    conda create --name venv python=3.8
+    conda activate venv
+
+Similar to a virtual environment created with ``virtualenv``, a conda environment
+is a space where you can install Python packages that are isolated from other virtual
+environments. In general, you should use ``conda install`` instead of ``pip install`` to install packages
+in a conda environment.
+
+Activate your newly created virtual environment using the above command whenever you want to work on HDMF. You can also
+deactivate it using the ``conda deactivate`` command to return to the base environment.
+
+.. _Anaconda: https://www.anaconda.com/distribution
+
+Install from GitHub
+-------------------
+
+After you have created and activated a virtual environment, clone the HDMF git repository from GitHub, install the
+package requirements using the pip_ Python package manager, and install HDMF in editable mode.
+
+.. _pip: https://pip.pypa.io/en/stable/
+
+.. code:: bash
+
+    git clone --recurse-submodules https://github.com/hdmf-dev/hdmf.git
+    cd hdmf
+    pip install -r requirements.txt -r requirements-dev.txt -r requirements-doc.txt
+    pip install -e .
+
+.. note::
+
+   When using ``conda``, you may use ``pip install`` to install dependencies as shown above; however, it is generally
+   recommended that dependencies should be installed via ``conda install``, e.g.,
+
+   .. code:: bash
+
+      conda install --file=requirements.txt --file=requirements-dev.txt --file=requirements-doc.txt
+
+Run tests
+---------
+
+You can run the full test suite with the following command:
+
+.. code:: bash
+
+    python test.py
+
+You could also run the full test suite by installing and running the ``pytest`` tool,
+a popular testing tool that provides more options for configuring test runs.
+
+First, install ``pytest``:
+
+.. code:: bash
+
+    pip install pytest
+
+Then run the full test suite:
+
+.. code:: bash
+
+    pytest
+
+You can also run a specific test module or class, or you can configure ``pytest`` to start the
+Python debugger (PDB) prompt on an error, e.g.,
+
+.. code:: bash
+
+    pytest tests/unit/test_container.py                                   # run all tests in the module
+    pytest tests/unit/test_container.py::TestContainer                    # run all tests in this class
+    pytest tests/unit/test_container.py::TestContainer::test_constructor  # run this test method
+    pytest --pdb tests/unit/test_container.py                             # start pdb on error
+
+
+Finally, you can run tests across multiple Python versions using the tox_ automated testing tool. Running ``tox`` will
+create a virtual environment, install dependencies, and run the test suite for Python 3.6, 3.7, 3.8, and 3.9.
+This can take some time to run.
+
+.. _pytest: https://docs.pytest.org/
+.. _tox: https://tox.readthedocs.io/en/latest/
+
+.. code:: bash
+
+    tox
+
+Install latest pre-release
+--------------------------
+
+To try out the latest features or set up continuous integration of your own project against the
+latest version of HDMF, install the latest release from GitHub.
+
+.. code:: bash
+
+    pip install -U hdmf --find-links https://github.com/hdmf-dev/hdmf/releases/tag/latest --no-index
diff --git a/docs/source/install_users.rst b/docs/source/install_users.rst
@@ -0,0 +1,32 @@
+..  _install_users:
+
+---------------
+Installing HDMF
+---------------
+
+HDMF requires having Python 3.6, 3.7, or 3.8 installed. If you don't have Python installed and want the simplest way to
+get started, we recommend you install and use the `Anaconda Distribution`_. It includes Python, NumPy, and many other
+commonly used packages for scientific computing and data science.
+
+HDMF can be installed with ``pip``, ``conda``, or from source. HDMF works on Windows, macOS, and Linux.
+
+Option 1: Using pip
+-------------------
+
+If you are a beginner to programming in Python and using Python tools, we recommend that you install HDMF by running
+the following command in a terminal or command prompt:
+
+.. code::
+
+   pip install hdmf
+
+Option 2: Using conda
+---------------------
+
+You can also install HDMF using ``conda`` by running the following command in a terminal or command prompt:
+
+.. code::
+
+   conda install -c conda-forge hdmf
+
+.. _Anaconda Distribution: https://www.anaconda.com/distribution