From 54f4980e3be54f2c05582371d25b76074e160d40 Mon Sep 17 00:00:00 2001 From: Ryan Ly Date: Sun, 24 Nov 2024 23:00:02 -0800 Subject: [PATCH] Prepare for release of NWB schema 2.8.0 (#597) --- .github/PULL_REQUEST_TEMPLATE/release.md | 5 ++-- .github/workflows/check_sphinx_links.yml | 16 +++++----- .github/workflows/validate_schema.yml | 33 ++++++++++++--------- README.rst | 6 ++-- core/nwb.file.yaml | 2 +- core/nwb.namespace.yaml | 2 +- docs/format/Readme.md | 2 +- docs/format/source/conf.py | 10 ++----- docs/format/source/credits.rst | 2 +- docs/format/source/format_description.rst | 10 +++---- docs/format/source/format_release_notes.rst | 15 ++++++---- docs/storage/Readme.md | 2 +- docs/storage/source/conf.py | 4 --- docs/storage/source/credits.rst | 2 +- docs/storage/source/storage_description.rst | 4 +-- 15 files changed, 57 insertions(+), 58 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE/release.md b/.github/PULL_REQUEST_TEMPLATE/release.md index ea0042f9..180aff41 100644 --- a/.github/PULL_REQUEST_TEMPLATE/release.md +++ b/.github/PULL_REQUEST_TEMPLATE/release.md @@ -11,8 +11,9 @@ Target release date: [date] - [ ] Update `docs/format/source/conf.py` as needed - [ ] Update release notes (set release date) in `docs/format/source/format_release_notes.rst` and any other docs as needed -- [ ] Test docs locally (`cd docs/format; make fulldoc`) where the nwb-schema submodule in the local version of PyNWB - is fully up-to-date with the head of the dev branch. +- [ ] Test docs locally (`cd docs/format; make fulldoc`) and check for warnings and errors +- [ ] Ensure PyNWB and MatNWB have branches that have passing tests when using the head of the dev branch or this + branch of nwb-schema - [ ] Push changes to this PR and make sure all PRs to be included in this release have been merged - [ ] Check that the readthedocs build for this PR succeeds (see auto-triggered PR build): https://readthedocs.org/projects/nwb-schema/builds/ diff --git a/.github/workflows/check_sphinx_links.yml b/.github/workflows/check_sphinx_links.yml index f2595eb9..7a199f3d 100644 --- a/.github/workflows/check_sphinx_links.yml +++ b/.github/workflows/check_sphinx_links.yml @@ -8,20 +8,18 @@ on: jobs: check-external-links: runs-on: ubuntu-latest + concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true steps: - - name: Cancel non-latest runs - uses: styfle/cancel-workflow-action@0.11.0 - with: - all_but_latest: true - access_token: ${{ github.token }} - - - uses: actions/checkout@v4 + - name: Checkout repo with submodules + uses: actions/checkout@v4 with: submodules: 'recursive' fetch-depth: 0 # tags are required for versioneer to determine the version - name: Set up Python - uses: actions/setup-python@v4 + uses: actions/setup-python@v5 with: python-version: '3.12' @@ -31,4 +29,4 @@ jobs: python -m pip install -r requirements-doc.txt - name: Check Sphinx links and references - run: sphinx-build -n -b linkcheck ./docs/format/source ./test_build + run: sphinx-build -n -W -b linkcheck ./docs/format/source ./test_build diff --git a/.github/workflows/validate_schema.yml b/.github/workflows/validate_schema.yml index 914586ca..752c39aa 100644 --- a/.github/workflows/validate_schema.yml +++ b/.github/workflows/validate_schema.yml @@ -1,21 +1,26 @@ name: Validate schema -on: [push, pull_request, workflow_dispatch] +on: + push: + branches: + - dev + pull_request: + workflow_dispatch: jobs: validate: - # run pipeline on either a push event or a PR event on a fork - if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.event.pull_request.base.repo.full_name runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 - - name: Set up Python 3.12 - uses: actions/setup-python@v4 - with: - python-version: "3.12" - - name: Install dev branch of HDMF - run: | - pip install git+https://github.com/hdmf-dev/hdmf.git - - name: Validate schema specification - run: | - validate_hdmf_spec core -m nwb.schema.json + - name: Checkout repo + uses: actions/checkout@v4 + + - name: Set up Python 3.12 + uses: actions/setup-python@v5 + with: + python-version: "3.12" + + - name: Install dev branch of HDMF + run: pip install git+https://github.com/hdmf-dev/hdmf.git + + - name: Validate schema specification + run: validate_hdmf_spec core -m nwb.schema.json diff --git a/README.rst b/README.rst index 0edc8dfc..30cc0bbd 100644 --- a/README.rst +++ b/README.rst @@ -8,16 +8,16 @@ To get started using NWB, please go to the `NWB overview website `_ (editable `here `_) +* The `Documentation for the NWB schema `_ (editable `here `_) * The `HDF5 storage specification `_ (editable `here `_) -The NWB schema uses the [NWB specification language](http://schema-language.readthedocs.io/), +The NWB schema uses the [NWB specification language](https://schema-language.readthedocs.io/), which defines formal structures for describing the organization of complex data using basic concepts, e.g., Groups, Datasets, Attributes, and Links. For more information: -- Learn more about NWB and `nwb.org `_. +- Learn more about NWB and `nwb.org `_. - The PyNWB Python API for the NWB format is available on `Github `_ - The MatNWB Matlab API for the NWB format is available on `Github `_ diff --git a/core/nwb.file.yaml b/core/nwb.file.yaml index f3232ed0..e9d146e7 100644 --- a/core/nwb.file.yaml +++ b/core/nwb.file.yaml @@ -7,7 +7,7 @@ groups: attributes: - name: nwb_version dtype: text - value: "2.8.0-alpha" + value: "2.8.0" doc: File version string. Use semantic versioning, e.g. 1.2.1. This will be the name of the format with trailing major, minor and patch numbers. datasets: diff --git a/core/nwb.namespace.yaml b/core/nwb.namespace.yaml index aabf4534..dd967efe 100644 --- a/core/nwb.namespace.yaml +++ b/core/nwb.namespace.yaml @@ -57,4 +57,4 @@ namespaces: - doc: This source module contains neurodata_type for retinotopy data. source: nwb.retinotopy.yaml title: Retinotopy - version: "2.8.0-alpha" + version: "2.8.0" diff --git a/docs/format/Readme.md b/docs/format/Readme.md index a5076d5a..547a9ace 100644 --- a/docs/format/Readme.md +++ b/docs/format/Readme.md @@ -1,6 +1,6 @@ **Overview** -The NWB specification documentation uses Sphinx [http://www.sphinx-doc.org/en/stable/index.html](http://www.sphinx-doc.org/en/stable/index.html) +The NWB specification documentation uses Sphinx [https://www.sphinx-doc.org/en/stable/index.html](https://www.sphinx-doc.org/en/stable/index.html) **Prerequisites** diff --git a/docs/format/source/conf.py b/docs/format/source/conf.py index 8b0919b6..0a2f836b 100644 --- a/docs/format/source/conf.py +++ b/docs/format/source/conf.py @@ -83,9 +83,9 @@ def setup(app): # built documents. # # The short X.Y version. -version = '2.8.0-alpha' +version = '2.8.0' # The full version, including alpha/beta/rc tags. -release = '2.8.0-alpha' +release = '2.8.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -133,16 +133,12 @@ def setup(app): #html_theme = 'default' #html_theme = "sphinxdoc" html_theme = "sphinx_rtd_theme" -html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. #html_theme_options = {} -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". #html_title = None @@ -225,7 +221,7 @@ def setup(app): \setcounter{tocdepth}{3} \setcounter{secnumdepth}{6} \\usepackage{enumitem} -\setlistdepth{100} +\\setlistdepth{100} \\addto\\captionsenglish{\\renewcommand{\\contentsname}{Table of contents}} """, } diff --git a/docs/format/source/credits.rst b/docs/format/source/credits.rst index 21ed29ca..86226849 100644 --- a/docs/format/source/credits.rst +++ b/docs/format/source/credits.rst @@ -5,7 +5,7 @@ Credits Acknowledgments =============== -For details on the partners, members, and supporters of NWB please the http://www.nwb.org/ project website. +For details on the partners, members, and supporters of NWB please the https://www.nwb.org/ project website. For specific contributions to the format specification and this document see the change logs of the Git repository at https://github.com/NeurodataWithoutBorders/nwb-schema . diff --git a/docs/format/source/format_description.rst b/docs/format/source/format_description.rst index a35b1be4..7e98a5c5 100644 --- a/docs/format/source/format_description.rst +++ b/docs/format/source/format_description.rst @@ -17,9 +17,9 @@ The NWB format uses the following main primitives to hierarchically organize neu store metadata specific to the object they are associated with, and * A *Link* is a reference to another group or dataset. -The NWB format is formally described via formal specification documents using the `NWB specification language `_ . -HDF5 currently serves as the main format for storing data in the NWB format (see http://nwb-storage.readthedocs.io/en/latest/ for details). -The `PyNWB `_ API is available to enable users to efficiently interact with NWB format files. +The NWB format is formally described via formal specification documents using the `NWB specification language `_ . +HDF5 currently serves as the main format for storing data in the NWB format (see https://nwb-storage.readthedocs.io/en/latest/ for details). +The `PyNWB `_ API is available to enable users to efficiently interact with NWB format files. The NWB format uses a modular design in which all main semantic components of the format have a unique *neurodata_type* (similar to a Class in object-oriented design)(:numref:`sec_neurodata_type_intro`). @@ -167,7 +167,7 @@ allowing users to extend (i.e., add to) existing and create new neurodata_types definitions for storing custom data. To avoid collisions between extensions, extensions are defined as part of custom namespaces (which typically import the core NWB namespace). Extensions to the format are written using the -`Specification Language `_ . +`Specification Language `_ . To ease development of extensions, the PyNWB_ (and `HDMF `_ used by PyNWB) API provides dedicated data structures that support programmatic creation and use of extensions. An @@ -214,7 +214,7 @@ All NWB Groups and Datasets with an assigned neurodata_type have three required namespace of an extension - ``object_id`` (variable-length string) is a universally unique identifier for this object within its hierarchy. It should be set to the string representation of a random UUID version 4 value - (see `RFC 4122 `_) upon first creation. It is **not** a hash of the data. Files + (see `RFC 4122 `_) upon first creation. It is **not** a hash of the data. Files that contain the exact same data but were generated in different instances will have different ``object_id`` values. Currently, modification of an object does not require its ``object_id`` to be changed. diff --git a/docs/format/source/format_release_notes.rst b/docs/format/source/format_release_notes.rst index 636c5cb4..4fafbd91 100644 --- a/docs/format/source/format_release_notes.rst +++ b/docs/format/source/format_release_notes.rst @@ -3,16 +3,19 @@ Release Notes ============= -2.8.0 (Upcoming) ------------------------- +2.8.0 (November 24, 2024) +------------------------- -Minor changes +Major changes ^^^^^^^^^^^^^ -- Added optional ``was_generated_by`` attribute to ``NWBFile`` to store provenance information (#578) - Deprecated ``EventWaveform`` neurodata type. (#584) - Deprecated ``ImageMaskSeries`` neurodata type. (#583) + +Minor changes +^^^^^^^^^^^^^ +- Added optional ``was_generated_by`` attribute to ``NWBFile`` to store provenance information. (#578) - Made ``band_mean`` and ``band_std`` in ``DecompositionSeries`` optional. (#593) -- Added ``Device.model_number``, ``Device.model_name``, ``Device.serial_number`` (#594) +- Added ``Device.model_number``, ``Device.model_name``, ``Device.serial_number``. (#594) 2.7.0 (February 7, 2024) ------------------------ @@ -686,7 +689,7 @@ types. To address this challenge, NWB 2.0 integrates ``UnitTimes``, ``ClusterWav into the new column-based table ``units/`` (i.e., ``intervals/units``) (which still uses the optimized vector data storage to efficiently store spike times). See for discussions and `I674 on PyNWB `_ -(and related `I675 on PyNWB `_) and the pull +(and related `I239 on NWB Schema `_) and the pull request `PR684 on PyNWB `_ for detailed changes. diff --git a/docs/storage/Readme.md b/docs/storage/Readme.md index e5a399e2..2adb0023 100644 --- a/docs/storage/Readme.md +++ b/docs/storage/Readme.md @@ -1,6 +1,6 @@ **Overview** -The NWB-N specification documentation uses Sphinx [http://www.sphinx-doc.org/en/stable/index.html](http://www.sphinx-doc.org/en/stable/index.html) +The NWB specification documentation uses Sphinx [https://www.sphinx-doc.org/en/stable/index.html](https://www.sphinx-doc.org/en/stable/index.html) **Building the documentation** diff --git a/docs/storage/source/conf.py b/docs/storage/source/conf.py index 409d167b..c596b89f 100644 --- a/docs/storage/source/conf.py +++ b/docs/storage/source/conf.py @@ -102,7 +102,6 @@ #html_theme = 'default' #html_theme = "sphinxdoc" html_theme = "sphinx_rtd_theme" -html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] def setup(app): app.add_css_file("theme_overrides.css") # overrides for wide tables in RTD theme @@ -112,9 +111,6 @@ def setup(app): # documentation. #html_theme_options = {} -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". #html_title = None diff --git a/docs/storage/source/credits.rst b/docs/storage/source/credits.rst index 2da5cba1..692e6810 100644 --- a/docs/storage/source/credits.rst +++ b/docs/storage/source/credits.rst @@ -14,7 +14,7 @@ Oliver Ruebel and Andrew Tritt et al. in collaboration with the NWB community. Acknowledgments =============== -For details on the partners, funders, and supporters of NWB please the http://www.nwb.org/ project website. +For details on the partners, funders, and supporters of NWB please the https://www.nwb.org/ project website. For specific contributions to the format specification and this document see the change logs of the Git repository at https://github.com/NeurodataWithoutBorders/nwb-schema . diff --git a/docs/storage/source/storage_description.rst b/docs/storage/source/storage_description.rst index b58d8a4e..a3f3c302 100644 --- a/docs/storage/source/storage_description.rst +++ b/docs/storage/source/storage_description.rst @@ -8,8 +8,8 @@ NWB Storage What is the role of data storage? ================================= -The `NWB format specification `_ -defined using the `NWB specification language `_ +The `NWB format specification `_ +defined using the `NWB specification language `_ describes how to organize large collections of neuroscience data using basic primitives, e.g., Files, Groups, Datasets, Attributes, and Links to describe and hierarchically group data. The role of the data storage then is to store large collections of neuroscience data. In other words,