From 09a0a00e0915ebc66a0e42cbe6417c38397fa230 Mon Sep 17 00:00:00 2001 From: Simon Heybrock Date: Wed, 25 Oct 2023 08:40:43 +0200 Subject: [PATCH 1/7] Apply copier template --- .copier-answers.yml | 12 ++ .github/dependabot.yml | 12 +- .github/workflows/ci.yml | 44 ++--- .github/workflows/docs.yml | 21 ++- .github/workflows/nightly_at_main.yml | 36 ++++ .github/workflows/nightly_at_release.yml | 43 +++++ .github/workflows/python-version-ci | 1 + .github/workflows/release.yml | 101 ++++++------ .github/workflows/test.yml | 64 ++++++++ .gitignore | 6 +- .pre-commit-config.yaml | 4 +- CODE_OF_CONDUCT.md | 134 +++++++++++++++ CONTRIBUTING.md | 20 +++ README.md | 9 +- conda/meta.yaml | 6 +- docs/_static/anaconda-logo.svg | 103 ++++++++++++ docs/_static/css/custom.css | 21 +++ docs/_templates/class-template.rst | 31 ++++ docs/_templates/doc_version.html | 2 + docs/_templates/module-template.rst | 66 ++++++++ docs/about/index.md | 18 ++ docs/api-reference/index.md | 29 ++++ docs/buildconfig/config.yaml | 2 + docs/conf.py | 199 ++++++++--------------- docs/developer/coding-conventions.md | 117 +++++++++++++ docs/developer/dependency-management.md | 13 ++ docs/developer/getting-started.md | 91 +++++++++++ docs/developer/index.md | 16 ++ docs/extra_conf.py | 1 + docs/index.md | 16 ++ docs/user-guide/test.nxs | Bin 0 -> 8232 bytes pyproject.toml | 53 +++++- requirements/base.in | 5 +- requirements/base.txt | 12 +- requirements/ci.txt | 34 ++-- requirements/dev.in | 10 ++ requirements/dev.txt | 105 ++++++++++++ requirements/docs.txt | 177 +++++++++++--------- requirements/make_base.py | 48 ++++++ requirements/mypy.in | 2 + requirements/mypy.txt | 14 ++ requirements/nightly.in | 5 + requirements/nightly.txt | 24 +++ requirements/static.txt | 18 +- requirements/test.txt | 10 +- requirements/wheels.txt | 12 +- setup.cfg | 38 ----- src/scippnexus/__init__.py | 1 - tests/package_test.py | 7 + tox.ini | 36 ++-- 50 files changed, 1442 insertions(+), 407 deletions(-) create mode 100644 .copier-answers.yml create mode 100644 .github/workflows/nightly_at_main.yml create mode 100644 .github/workflows/nightly_at_release.yml create mode 100644 .github/workflows/python-version-ci create mode 100644 .github/workflows/test.yml create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 docs/_static/anaconda-logo.svg create mode 100644 docs/_static/css/custom.css create mode 100644 docs/_templates/class-template.rst create mode 100644 docs/_templates/doc_version.html create mode 100644 docs/_templates/module-template.rst create mode 100644 docs/about/index.md create mode 100644 docs/api-reference/index.md create mode 100644 docs/buildconfig/config.yaml create mode 100644 docs/developer/coding-conventions.md create mode 100644 docs/developer/dependency-management.md create mode 100644 docs/developer/getting-started.md create mode 100644 docs/developer/index.md create mode 100644 docs/extra_conf.py create mode 100644 docs/index.md create mode 100644 docs/user-guide/test.nxs create mode 100644 requirements/dev.in create mode 100644 requirements/dev.txt create mode 100644 requirements/make_base.py create mode 100644 requirements/mypy.in create mode 100644 requirements/mypy.txt create mode 100644 requirements/nightly.in create mode 100644 requirements/nightly.txt create mode 100644 tests/package_test.py diff --git a/.copier-answers.yml b/.copier-answers.yml new file mode 100644 index 00000000..f58e24fd --- /dev/null +++ b/.copier-answers.yml @@ -0,0 +1,12 @@ +# Changes here will be overwritten by Copier; NEVER EDIT MANUALLY +_commit: 542e56b +_src_path: gh:scipp/copier_template +description: An h5py-like utility for NeXus files with seamless Scipp integration +max_python: '3.12' +min_python: '3.8' +namespace_package: '' +nightly_deps: scipp +orgname: scipp +projectname: scippnexus +related_projects: Scipp,ScippNeutron +year: 2023 diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 4a4bf110..c8076bb1 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -1,13 +1,9 @@ version: 2 updates: - - package-ecosystem: "github-actions" - directory: "/" - schedule: - interval: "weekly" - ignore: - # Optional: Official actions have moving tags like v1; - # if you use those, you don't need updates. - - dependency-name: "actions/*" + # Note: We are not listing package-ecosystem: "github-actions". This causes + # noise in all template instances. Instead dependabot.yml in scipp/copier_template + # triggers updates of github-actions in the *template*. We then use `copier update` + # in template instances. - package-ecosystem: "pip" directory: "/requirements" schedule: diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index fd020e5d..0d294d17 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,3 +1,6 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright (c) 2023 Scipp contributors (https://github.com/scipp) + name: CI on: @@ -10,12 +13,20 @@ on: jobs: formatting: name: Formatting and static analysis - runs-on: ubuntu-20.04 + runs-on: 'ubuntu-20.04' + outputs: + min_python: ${{ steps.vars.outputs.min_python }} + min_tox_env: ${{ steps.vars.outputs.min_tox_env }} steps: - - uses: actions/checkout@v3 - - uses: actions/setup-python@v3 + - uses: actions/checkout@v4 + - name: Get Python version for other CI jobs + id: vars + run: | + echo "min_python=$(cat .github/workflows/python-version-ci)" >> $GITHUB_OUTPUT + echo "min_tox_env=py$(cat .github/workflows/python-version-ci | sed 's/\.//g')" >> $GITHUB_OUTPUT + - uses: actions/setup-python@v4 with: - python-version: '3.10' + python-version-file: '.github/workflows/python-version-ci' - run: python -m pip install --upgrade pip - run: python -m pip install -r requirements/ci.txt - run: tox -e static @@ -24,28 +35,23 @@ jobs: commit_message: Apply automatic formatting tests: - name: Tests ${{ matrix.name }} + name: Tests needs: formatting - runs-on: ubuntu-20.04 strategy: matrix: - include: - - {name: '3.10', python: '3.10', os: ubuntu-20.04, tox: py310} - - {name: '3.9', python: '3.9', os: ubuntu-20.04, tox: py39} - - {name: '3.8', python: '3.8', os: ubuntu-20.04, tox: py38} - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-python@v3 - with: - python-version: ${{ matrix.python }} - - run: python -m pip install --upgrade pip - - run: python -m pip install -r requirements/ci.txt - - run: tox -e ${{ matrix.tox }} + os: ['ubuntu-20.04'] + python: + - version: '${{needs.formatting.outputs.min_python}}' + tox-env: '${{needs.formatting.outputs.min_tox_env}}' + uses: ./.github/workflows/test.yml + with: + os-variant: ${{ matrix.os }} + python-version: ${{ matrix.python.version }} + tox-env: ${{ matrix.python.tox-env }} docs: needs: tests uses: ./.github/workflows/docs.yml with: publish: false - version: ${{ github.ref_name }} branch: ${{ github.head_ref == '' && github.ref_name || github.head_ref }} diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 094ed938..9dd22f19 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,3 +1,6 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright (c) 2023 Scipp contributors (https://github.com/scipp) + name: Docs on: @@ -36,27 +39,25 @@ env: jobs: docs: name: Build documentation - runs-on: ubuntu-20.04 + runs-on: 'ubuntu-20.04' steps: - run: sudo apt install --yes graphviz pandoc - uses: actions/checkout@v3 with: ref: ${{ inputs.branch == '' && github.ref_name || inputs.branch }} fetch-depth: 0 # history required so cmake can determine version - - uses: actions/setup-python@v3 + - uses: actions/setup-python@v4 with: - python-version: '3.8' + python-version-file: '.github/workflows/python-version-ci' - run: python -m pip install --upgrade pip - run: python -m pip install -r requirements/ci.txt - - run: | - tox --skip-pkg-install -e docs -- scippnexus==${VERSION} - echo "target=$(python docs/version.py --version=${VERSION} --action=get-target)" >> $GITHUB_ENV - if: ${{ inputs.publish }} + - run: tox -e releasedocs -- ${VERSION} + if: ${{ inputs.version != '' }} - run: tox -e docs - if: ${{ !inputs.publish }} + if: ${{ inputs.version == '' }} - uses: actions/upload-artifact@v3 with: - name: html + name: docs_html path: html/ - uses: JamesIves/github-pages-deploy-action@v4.4.3 @@ -64,7 +65,5 @@ jobs: with: branch: gh-pages folder: html - target-folder: ${{ env.target }} single-commit: true - clean-exclude: release ssh-key: ${{ secrets.GH_PAGES_DEPLOY_KEY }} diff --git a/.github/workflows/nightly_at_main.yml b/.github/workflows/nightly_at_main.yml new file mode 100644 index 00000000..67d31d87 --- /dev/null +++ b/.github/workflows/nightly_at_main.yml @@ -0,0 +1,36 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright (c) 2023 Scipp contributors (https://github.com/scipp) + +name: Nightly test at main branch + +on: + workflow_dispatch: + schedule: + - cron: '30 23 * * *' + +jobs: + setup: + name: Setup variables + runs-on: 'ubuntu-20.04' + outputs: + min_python: ${{ steps.vars.outputs.min_python }} + steps: + - uses: actions/checkout@v4 + - name: Get Python version for other CI jobs + id: vars + run: echo "min_python=$(cat .github/workflows/python-version-ci)" >> $GITHUB_OUTPUT + + tests: + name: Tests + needs: setup + strategy: + matrix: + os: ['ubuntu-20.04'] + python: + - version: '${{needs.setup.outputs.min_python}}' + tox-env: 'nightly' + uses: ./.github/workflows/test.yml + with: + os-variant: ${{ matrix.os }} + python-version: ${{ matrix.python.version }} + tox-env: ${{ matrix.python.tox-env }} diff --git a/.github/workflows/nightly_at_release.yml b/.github/workflows/nightly_at_release.yml new file mode 100644 index 00000000..b424c664 --- /dev/null +++ b/.github/workflows/nightly_at_release.yml @@ -0,0 +1,43 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright (c) 2023 Scipp contributors (https://github.com/scipp) + +name: Nightly tests at latest release + +on: + workflow_dispatch: + schedule: + - cron: '0 23 * * *' + +jobs: + setup: + name: Setup variables + runs-on: 'ubuntu-20.04' + outputs: + min_python: ${{ steps.vars.outputs.min_python }} + release_tag: ${{ steps.release.outputs.release_tag }} + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 # history required so we can determine latest release tag + - name: Get last release tag from git + id: release + run: echo "release_tag=$(git describe --tags --abbrev=0 --match '[0-9]*.[0-9]*.[0-9]*')" >> $GITHUB_OUTPUT + - name: Get Python version for other CI jobs + id: vars + run: echo "min_python=$(cat .github/workflows/python-version-ci)" >> $GITHUB_OUTPUT + + tests: + name: Tests + needs: setup + strategy: + matrix: + os: ['ubuntu-20.04'] + python: + - version: '${{needs.setup.outputs.min_python}}' + tox-env: 'nightly' + uses: ./.github/workflows/test.yml + with: + os-variant: ${{ matrix.os }} + python-version: ${{ matrix.python.version }} + tox-env: ${{ matrix.python.tox-env }} + checkout_ref: ${{ needs.setup.outputs.release_tag }} diff --git a/.github/workflows/python-version-ci b/.github/workflows/python-version-ci new file mode 100644 index 00000000..cc1923a4 --- /dev/null +++ b/.github/workflows/python-version-ci @@ -0,0 +1 @@ +3.8 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index d3efd2f0..223dd5af 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,3 +1,6 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright (c) 2023 Scipp contributors (https://github.com/scipp) + name: Release on: @@ -12,35 +15,39 @@ defaults: jobs: build_conda: name: Conda build - runs-on: ubuntu-20.04 + runs-on: 'ubuntu-20.04' steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 with: submodules: true - fetch-depth: 0 # history required so cmake can determine version + fetch-depth: 0 # history required so setuptools_scm can determine version - - uses: conda-incubator/setup-miniconda@v2 - - run: conda install --yes conda-build - - run: conda build --channel conda-forge --channel scipp --python=3.8 --no-anaconda-upload --override-channels --output-folder conda/package conda + - uses: mamba-org/setup-micromamba@v1 + with: + environment-name: build-env + create-args: >- + conda-build + boa + - run: conda mambabuild --channel conda-forge --channel scipp --no-anaconda-upload --override-channels --output-folder conda/package conda - - uses: actions/upload-artifact@v2 + - uses: actions/upload-artifact@v3 with: name: conda-package-noarch - path: conda/package/*/scippnexus*.tar.bz2 + path: conda/package/noarch/*.tar.bz2 build_wheels: name: Wheels - runs-on: ubuntu-20.04 + runs-on: 'ubuntu-20.04' steps: - uses: actions/checkout@v3 with: fetch-depth: 0 # history required so setuptools_scm can determine version - - uses: actions/setup-python@v3 + - uses: actions/setup-python@v4 with: - python-version: '3.8' + python-version-file: '.github/workflows/python-version-ci' - run: python -m pip install --upgrade pip - run: python -m pip install -r requirements/wheels.txt @@ -57,65 +64,53 @@ jobs: upload_pypi: name: Deploy PyPI needs: [build_wheels, build_conda] - runs-on: ubuntu-20.04 + runs-on: 'ubuntu-20.04' + environment: release + permissions: + id-token: write if: github.event_name == 'release' && github.event.action == 'published' - steps: - uses: actions/download-artifact@v3 - - uses: actions/setup-python@v3 - uses: pypa/gh-action-pypi-publish@v1.8.10 - with: - user: __token__ - password: ${{ secrets.PYPI_TOKEN }} upload_conda: - name: Deploy Conda Forge + name: Deploy Conda needs: [build_wheels, build_conda] - runs-on: ubuntu-20.04 + runs-on: 'ubuntu-20.04' if: github.event_name == 'release' && github.event.action == 'published' steps: - uses: actions/download-artifact@v3 - - uses: conda-incubator/setup-miniconda@v2 + - uses: mamba-org/setup-micromamba@v1 with: - python-version: '3.10' - - run: conda install -c conda-forge --yes anaconda-client - - run: anaconda --token ${{ secrets.ANACONDATOKEN }} upload --user scipp --label main $(ls conda-package-*/*/*.tar.bz2) - - manage-versions: - name: Manage Versions - runs-on: ubuntu-20.04 - outputs: - version-new: ${{ steps.version.outputs.new }} - version-replaced: ${{ steps.version.outputs.replaced }} - steps: - - uses: actions/checkout@v3 - with: - fetch-depth: 0 # history required so cmake can determine version - - uses: actions/setup-python@v3 - with: - python-version: '3.8' - - run: python -m pip install --upgrade pip - - run: python -m pip install -r requirements/ci.txt - - name: Set outputs - id: version - run: | - echo "new=$(python docs/version.py --version=${GITHUB_REF_NAME} --action=is-new)" >> $GITHUB_OUTPUT - echo "replaced=$(python docs/version.py --version=${GITHUB_REF_NAME} --action=get-replaced)" >> $GITHUB_OUTPUT + environment-name: upload-env + # frozen python due to breaking removal of 'imp' in 3.12 + create-args: >- + anaconda-client + python=3.11 + - run: anaconda --token ${{ secrets.ANACONDATOKEN }} upload --user scipp --label main $(ls conda-package-noarch/*.tar.bz2) docs: - needs: [upload_conda, upload_pypi, manage-versions] + needs: [upload_conda, upload_pypi] uses: ./.github/workflows/docs.yml with: publish: ${{ github.event_name == 'release' && github.event.action == 'published' }} - version: ${{ github.ref_name }} secrets: inherit - replaced-docs: + assets: + name: Upload docs needs: docs - if: github.event_name == 'release' && github.event.action == 'published' && needs.manage-versions.outputs.version-new == 'True' - uses: ./.github/workflows/docs.yml - with: - publish: true - version: ${{ needs.manage-versions.outputs.version-replaced }} - secrets: inherit + runs-on: 'ubuntu-20.04' + permissions: + contents: write # This is needed so that the action can upload the asset + steps: + - uses: actions/download-artifact@v3 + - name: Zip documentation + run: | + mv docs_html documentation-${{ github.ref_name }} + zip -r documentation-${{ github.ref_name }}.zip documentation-${{ github.ref_name }} + - name: Upload release assets + uses: svenstaro/upload-release-action@v2 + with: + file: ./documentation-${{ github.ref_name }}.zip + overwrite: false diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml new file mode 100644 index 00000000..8ce71be0 --- /dev/null +++ b/.github/workflows/test.yml @@ -0,0 +1,64 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright (c) 2023 Scipp contributors (https://github.com/scipp) + +name: Test + +on: + workflow_dispatch: + inputs: + os-variant: + default: 'ubuntu-20.04' + type: string + python-version: + type: string + tox-env: + default: 'test' + type: string + pip-recipe: + default: 'requirements/ci.txt' + type: string + coverage-report: + default: false + type: boolean + checkout_ref: + default: '' + type: string + workflow_call: + inputs: + os-variant: + default: 'ubuntu-20.04' + type: string + python-version: + type: string + tox-env: + default: 'test' + type: string + pip-recipe: + default: 'requirements/ci.txt' + type: string + coverage-report: + default: false + type: boolean + checkout_ref: + default: '' + type: string + +jobs: + test: + runs-on: ${{ inputs.os-variant }} + + steps: + - uses: actions/checkout@v3 + with: + ref: ${{ inputs.checkout_ref }} + - uses: actions/setup-python@v3 + with: + python-version: ${{ inputs.python-version }} + - run: python -m pip install --upgrade pip + - run: python -m pip install -r ${{ inputs.pip-recipe }} + - run: tox -e ${{ inputs.tox-env }} + - uses: actions/upload-artifact@v3 + if: ${{ inputs.coverage-report }} + with: + name: CoverageReport + path: coverage_html/ diff --git a/.gitignore b/.gitignore index 1aaa873d..9bd926bc 100644 --- a/.gitignore +++ b/.gitignore @@ -1,20 +1,18 @@ -build dist +html .tox src/scippnexus.egg-info *.sw? -compile_commands.json .clangd/ .idea/ .vscode/ *.ipynb_checkpoints __pycache__/ -CMakeSettings.json .vs/ .virtual_documents .hypothesis .pytest_cache .mypy_cache -docs/generated/ \ No newline at end of file +docs/generated/ diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 9f068c3e..a8b47569 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -17,8 +17,8 @@ repos: hooks: - id: isort name: isort (python) - - repo: https://github.com/psf/black - rev: 23.1.0 + - repo: https://github.com/psf/black-pre-commit-mirror + rev: 23.9.0 hooks: - id: black - repo: https://github.com/kynan/nbstripout diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..ff33c0e1 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,134 @@ + +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +scipp@ess.eu. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..b6f184cc --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,20 @@ +## Contributing to Scippnexus + +Welcome to the developer side of Scippnexus! + +Contributions are always welcome. +This includes reporting bugs or other issues, submitting pull requests, requesting new features, etc. + +If you need help with using Scippnexus or contributing to it, have a look at the GitHub [discussions](https://github.com/scipp/scippnexus/discussions) and start a new [Q&A discussion](https://github.com/scipp/scippnexus/discussions/categories/q-a) if you can't find what you are looking for. + +For bug reports and other problems, please open an [issue](https://github.com/scipp/scippnexus/issues/new) in GitHub. + +You are welcome to submit pull requests at any time. +But to avoid having to make large modifications during review or even have your PR rejected, please first open an issue first to discuss your idea! + +Check out the subsections of the [Developer documentation](https://scipp.github.io/scippnexus/developer/index.html) for details on how Scippnexus is developed. + +## Code of conduct + +This project is a community effort, and everyone is welcome to contribute. +Everyone within the community is expected to abide by our [code of conduct](https://github.com/scipp/scippnexus/blob/main/CODE_OF_CONDUCT.md). diff --git a/README.md b/README.md index 1445ef9d..98188338 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,4 @@ +[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md) [![PyPI badge](http://img.shields.io/pypi/v/scippnexus.svg)](https://pypi.python.org/pypi/scippnexus) [![Anaconda-Server Badge](https://anaconda.org/scipp/scippnexus/badges/version.svg)](https://anaconda.org/scipp/scippnexus) [![License: BSD 3-Clause](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](LICENSE) @@ -15,11 +16,3 @@ See the [documentation](https://scipp.github.io/scippnexus) for more details. ```sh python -m pip install scippnexus ``` - -## Contributing Organizations - -The following organizations have made major contributions to the development of ScippNexus: - -* [European Spallation Source ERIC](https://europeanspallationsource.se/), Sweden - -See individual [release notes](https://scipp.github.io/scippnexus/about/release-notes.html) for the individual contributors to each release. diff --git a/conda/meta.yaml b/conda/meta.yaml index a81c09d0..34a28974 100644 --- a/conda/meta.yaml +++ b/conda/meta.yaml @@ -1,6 +1,8 @@ package: name: scippnexus + version: {{ GIT_DESCRIBE_TAG }} + source: path: .. @@ -34,7 +36,7 @@ build: about: home: https://github.com/scipp/scippnexus license: BSD-3-Clause - summary: An h5py-like utility for NeXus files based with seamless scipp integration - description: An h5py-like utility for NeXus files based with seamless scipp integration + summary: An h5py-like utility for NeXus files with seamless Scipp integration + description: An h5py-like utility for NeXus files with seamless Scipp integration dev_url: https://github.com/scipp/scippnexus doc_url: https://scipp.github.io/scippnexus diff --git a/docs/_static/anaconda-logo.svg b/docs/_static/anaconda-logo.svg new file mode 100644 index 00000000..67bd68d9 --- /dev/null +++ b/docs/_static/anaconda-logo.svg @@ -0,0 +1,103 @@ + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css new file mode 100644 index 00000000..d7fabbbb --- /dev/null +++ b/docs/_static/css/custom.css @@ -0,0 +1,21 @@ +html[data-theme="light"] { + /* match pst-color-text-muted (used in header buttons) */ + --scipp-filter-header-icon: saturate(0) brightness(0.696); +} + +html[data-theme="dark"] { + /* match pst-color-text-muted (used in header buttons) */ + --scipp-filter-header-icon: saturate(0) brightness(1.161); +} + +/* This selects custom icon links in the header but not the builtin ones. + * Currently, this is only the anaconda logo and the filters are adjusted to it. + */ +.bd-header .navbar-nav li a.nav-link .icon-link-image { + filter: var(--scipp-filter-header-icon); +} + +.bd-header .navbar-nav li a.nav-link .icon-link-image:hover { + /* match primary color */ + filter: hue-rotate(85deg) saturate(0.829) brightness(0.945); +} diff --git a/docs/_templates/class-template.rst b/docs/_templates/class-template.rst new file mode 100644 index 00000000..0200267d --- /dev/null +++ b/docs/_templates/class-template.rst @@ -0,0 +1,31 @@ +{{ fullname | escape | underline }} + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + :members: + :special-members: __getitem__ + + {% block methods %} + .. automethod:: __init__ + + {% if methods %} + .. rubric:: {{ _('Methods') }} + + .. autosummary:: + {% for item in methods %} + ~{{ name }}.{{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block attributes %} + {% if attributes %} + .. rubric:: {{ _('Attributes') }} + + .. autosummary:: + {% for item in attributes %} + ~{{ name }}.{{ item }} + {%- endfor %} + {% endif %} + {% endblock %} diff --git a/docs/_templates/doc_version.html b/docs/_templates/doc_version.html new file mode 100644 index 00000000..7fd881ac --- /dev/null +++ b/docs/_templates/doc_version.html @@ -0,0 +1,2 @@ + +Current {{ project }} version: {{ version }} (older versions). diff --git a/docs/_templates/module-template.rst b/docs/_templates/module-template.rst new file mode 100644 index 00000000..6fee8d77 --- /dev/null +++ b/docs/_templates/module-template.rst @@ -0,0 +1,66 @@ +{{ fullname | escape | underline}} + +.. automodule:: {{ fullname }} + + {% block attributes %} + {% if attributes %} + .. rubric:: {{ _('Module Attributes') }} + + .. autosummary:: + :toctree: + {% for item in attributes %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block functions %} + {% if functions %} + .. rubric:: {{ _('Functions') }} + + .. autosummary:: + :toctree: + {% for item in functions %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block classes %} + {% if classes %} + .. rubric:: {{ _('Classes') }} + + .. autosummary:: + :toctree: + :template: class-template.rst + {% for item in classes %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block exceptions %} + {% if exceptions %} + .. rubric:: {{ _('Exceptions') }} + + .. autosummary:: + :toctree: + {% for item in exceptions %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + +{% block modules %} +{% if modules %} +.. rubric:: Modules + +.. autosummary:: + :toctree: + :template: module-template.rst + :recursive: +{% for item in modules %} + {{ item }} +{%- endfor %} +{% endif %} +{% endblock %} diff --git a/docs/about/index.md b/docs/about/index.md new file mode 100644 index 00000000..9e37d545 --- /dev/null +++ b/docs/about/index.md @@ -0,0 +1,18 @@ +# About Scippnexus + +## Development + +Scippnexus is an open source project by the [European Spallation Source ERIC](https://europeanspallationsource.se/) (ESS). + +## License + +Scippnexus is available as open source under the [BSD-3 license](https://opensource.org/licenses/BSD-3-Clause). + +## Older versions of the documentation + +Older versions of the documentation pages can be found under the assets of each [release](https://github.com/scipp/scippnexus/releases). +Simply download the archive, unzip and view locally in a web browser. + +## Source code and development + +Scippnexus is hosted and developed [on GitHub](https://github.com/scipp/scippnexus). diff --git a/docs/api-reference/index.md b/docs/api-reference/index.md new file mode 100644 index 00000000..db8f9d85 --- /dev/null +++ b/docs/api-reference/index.md @@ -0,0 +1,29 @@ +# API Reference + +## Classes + +```{eval-rst} +.. currentmodule:: scippnexus + +.. autosummary:: + :toctree: ../generated/classes + :template: class-template.rst + :recursive: +``` + +## Top-level functions + +```{eval-rst} +.. autosummary:: + :toctree: ../generated/functions + :recursive: +``` + +## Submodules + +```{eval-rst} +.. autosummary:: + :toctree: ../generated/modules + :template: module-template.rst + :recursive: +``` \ No newline at end of file diff --git a/docs/buildconfig/config.yaml b/docs/buildconfig/config.yaml new file mode 100644 index 00000000..0328bb51 --- /dev/null +++ b/docs/buildconfig/config.yaml @@ -0,0 +1,2 @@ +plot: + use_plopp: true diff --git a/docs/conf.py b/docs/conf.py index eae47238..e42480c6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -3,97 +3,56 @@ import doctest import os import sys -from datetime import date -from typing import Any, Dict, Optional - -import sphinx_book_theme -from docutils.nodes import document -from sphinx.application import Sphinx import scippnexus sys.path.insert(0, os.path.abspath('.')) -from version import VersionInfo # noqa: E402 - # General information about the project. project = u'scippnexus' copyright = u'2023 Scipp contributors' author = u'Scipp contributors' -version_info = VersionInfo() -long_version = scippnexus.__version__ -outdated = not version_info.is_latest(long_version) - - -def add_buttons( - app: Sphinx, - pagename: str, - templatename: str, - context: Dict[str, Any], - doctree: Optional[document], -): - base = "https://scipp.github.io" - l1 = [] - l1.append({"type": "link", "text": "scipp", "url": f"{base}"}) - l1.append({"type": "link", "text": "scippnexus", "url": f"{base}/scippnexus"}) - l1.append({"type": "link", "text": "scippneutron", "url": f"{base}/scippneutron"}) - l1.append({"type": "link", "text": "ess", "url": f"{base}/ess"}) - header_buttons = context["header_buttons"] - header_buttons.append( - { - "type": "group", - "buttons": l1, - "icon": "fa fa-caret-down", - "text": "Related projects", - } - ) - releases = version_info.minor_releases(first='0.1') - if outdated: - current = f"{long_version} (outdated)" - latest = "latest" - entries = ['.'.join(long_version.split('.')[:2])] - else: - current = f"{long_version} (latest)" - latest = f"{releases[0]} (latest)" - entries = releases[1:] - lines = [{"type": "link", "text": latest, "url": f"{base}/{project}"}] - for r in entries: - lines.append( - {"type": "link", "text": f"{r}", "url": f"{base}/{project}/release/{r}"} - ) - header_buttons.append( - {"type": "group", "buttons": lines, "icon": "fa fa-caret-down", "text": current} - ) - - -sphinx_book_theme.add_launch_buttons = add_buttons - html_show_sourcelink = True extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.doctest', + 'sphinx.ext.githubpages', 'sphinx.ext.intersphinx', 'sphinx.ext.mathjax', 'sphinx.ext.napoleon', 'sphinx_autodoc_typehints', 'sphinx_copybutton', + "sphinx_design", 'nbsphinx', + 'myst_parser', ] +myst_enable_extensions = [ + "amsmath", + "colon_fence", + "deflist", + "dollarmath", + "fieldlist", + "html_admonition", + "html_image", + "replacements", + "smartquotes", + "strikethrough", + "substitution", + "tasklist", +] + +myst_heading_anchors = 3 + autodoc_type_aliases = { 'VariableLike': 'VariableLike', 'MetaDataMap': 'MetaDataMap', 'array_like': 'array_like', } -rst_epilog = f""" -.. |SCIPP_RELEASE_MONTH| replace:: {date.today().strftime("%B %Y")} -.. |SCIPP_VERSION| replace:: {scippnexus.__version__} -""" # noqa: E501 - intersphinx_mapping = { 'python': ('https://docs.python.org/3', None), 'numpy': ('https://numpy.org/doc/stable/', None), @@ -129,8 +88,7 @@ def add_buttons( # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # -# source_suffix = ['.rst', '.md'] -source_suffix = '.rst' +source_suffix = ['.rst', '.md'] html_sourcelink_suffix = '' # Avoid .ipynb.txt extensions in sources # The master toctree document. @@ -140,10 +98,11 @@ def add_buttons( # |version| and |release|, also used in various other places throughout the # built documents. # + # The short X.Y version. -version = u'' +version = scippnexus.__version__ # The full version, including alpha/beta/rc tags. -release = u'' +release = scippnexus.__version__ warning_is_error = True @@ -152,7 +111,7 @@ def add_buttons( # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +language = "en" # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. @@ -167,82 +126,68 @@ def add_buttons( # -- Options for HTML output ---------------------------------------------- -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# - -html_theme = 'sphinx_book_theme' - -# 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 = "pydata_sphinx_theme" html_theme_options = { - "logo_only": True, - "repository_url": f"https://github.com/scipp/{project}", - "repository_branch": "main", - "path_to_docs": "docs", - "use_repository_button": True, - "use_issues_button": True, - "use_edit_page_button": True, - "show_toc_level": 2, # Show subheadings in secondary sidebar + "primary_sidebar_end": ["edit-this-page", "sourcelink"], + "secondary_sidebar_items": [], + "show_nav_level": 1, + # Adjust this to ensure external links are moved to "Move" menu + "header_links_before_dropdown": 4, + "pygment_light_style": "github-light-high-contrast", + "pygment_dark_style": "github-dark-high-contrast", + "logo": { + "image_light": "_static/logo.svg", + "image_dark": "_static/logo-dark.svg", + }, + "external_links": [ + {"name": "Scipp", "url": "https://scipp.github.io"}, + {"name": "ScippNeutron", "url": "https://scipp.github.io/scippneutron"}, + ], + "icon_links": [ + { + "name": "GitHub", + "url": "https://github.com/scipp/scippnexus", + "icon": "fa-brands fa-github", + "type": "fontawesome", + }, + { + "name": "PyPI", + "url": "https://pypi.org/project/scippnexus/", + "icon": "fa-brands fa-python", + "type": "fontawesome", + }, + { + "name": "Conda", + "url": "https://anaconda.org/conda-forge/scippnexus", + "icon": "_static/anaconda-logo.svg", + "type": "local", + }, + ], + "footer_start": ["copyright", "sphinx-version"], + "footer_end": ["doc_version", "theme-version"], +} +html_context = { + "doc_path": "docs", +} +html_sidebars = { + "**": ["sidebar-nav-bs", "page-toc"], } -if outdated: - html_theme_options["announcement"] = ( - f"⚠️ You are viewing the documentation for an old version of {project}. " - f"Switch to latest version. ⚠️" - ) - -html_logo = "_static/logo-2022.svg" +html_title = "scippnexus" +html_logo = "_static/logo.svg" html_favicon = "_static/favicon.ico" # 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_css_files = ["css/custom.css"] # -- Options for HTMLHelp output ------------------------------------------ # Output file base name for HTML help builder. htmlhelp_basename = 'scippnexusdoc' -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = {} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (master_doc, 'scipp.tex', u'scipp Documentation', u'Simon Heybrock', 'manual'), -] - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [(master_doc, 'scipp', u'scipp Documentation', [author], 1)] - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ( - master_doc, - 'scipp', - u'scipp Documentation', - author, - 'scipp', - 'One line description of project.', - 'Miscellaneous', - ), -] - # -- Options for Matplotlib in notebooks ---------------------------------- nbsphinx_execute_arguments = [ diff --git a/docs/developer/coding-conventions.md b/docs/developer/coding-conventions.md new file mode 100644 index 00000000..b23c0eb4 --- /dev/null +++ b/docs/developer/coding-conventions.md @@ -0,0 +1,117 @@ +# Coding conventions + +## Code formatting + +There are no explicit code formatting conventions since we use `black` to enforce a format. + +## Docstring format + +We use the [NumPy docstring format](https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html). +We use `sphinx-autodocs-typehints` to automatically insert type hints into the docstrings. +Our format thus deviates from the default NumPy example given by the link above. +Docstrings should therefore be laid out as follows, including spacing and punctuation: + +```python + +def foo(x: int, y: float) -> float: + """Short description. + + Long description. + + With multiple paragraphs. + + Warning + ------- + Be careful! + + Parameters + ---------- + x: + First input. + y: + Second input. + + Returns + ------- + : + The result. + + Raises + ------ + ValueError + If the input is bad. + IndexError + If some lookup failed. + + See Also + -------- + scitacean.bar: + A bit less foo. + + Examples + -------- + This is how to use it: + + >>> foo(1, 2) + 3 + + And also: + + >>> foo(1, 3) + 6 + """ +``` + +The order of sections is fixed as shown in the example. + +- **Short description** (*required*) A single sentence describing the purpose of the function / class. +- **Long description** (*optional*) One or more paragraphs of detailed explanations. + Can include additional sections like `Warning` or `Hint`. +- **Parameters** (*required for functions*) List of all function arguments including their name but not their type. + Listing arguments like this can seem ridiculous if the explanation is as devoid of content as in the example. + But it is still required in order for sphinx to show the types. +- **Returns** (*required for functions*) Description of the return value. + Required for the same reason as the parameter list. + + For a single return value, neither a name nor type should be given. + But a colon is required as in the example above in order to produce proper formatting. + + For multiple return values, to produce proper formatting, + both name and type must be given even though the latter repeats the type annotation: + + ```python + + """ + Returns + ------- + n: int + The first return value. + z: float + The second return value. + """ + ``` + +- **Raises** (*optional*) We generally do not document what exceptions can be raised from a function. + But if there are some important cases, this section can list those exceptions with an explanation + of when the exception is raised. + The exception type is required. + Note that there are no colons here. +- **See Also** (*optional*) List of related functions and/or classes. + The function/class name should include the module it is in but without reST markup. + For simple cases, the explanation can be left out. + In this case, the colon should be omitted as well and multiple entries must be separated by commas. +- **Examples** (*optional*) Example code given using `>>>` as the Python prompt. + May include text before, after, and between code blocks. + Note the spacing in the example. + +Some functions can be sufficiently described by a single sentence. +In this case, the 'Parameters' and 'Returns' sections may be omitted and the docstring should be laid out on a single line. +If it does not fit on a single line, it is too complicated. +For example + +```python +def bar(self) -> int: + """Returns the number of dimensions.""" +``` + +Note that the argument types are not shown in the rendered documentation. diff --git a/docs/developer/dependency-management.md b/docs/developer/dependency-management.md new file mode 100644 index 00000000..41100ca0 --- /dev/null +++ b/docs/developer/dependency-management.md @@ -0,0 +1,13 @@ +# Dependency management + +scippnexus is a library, so the package dependencies are never pinned. +Lower bounds are fine and individual versions can be excluded. +See, e.g., [Should You Use Upper Bound Version Constraints](https://iscinumpy.dev/post/bound-version-constraints/) for an explanation. + +Development dependencies (as opposed to dependencies of the deployed package that users need to install) are pinned to an exact version in order to ensure reproducibility. +This also includes dependencies used for the various CI builds. +This is done by specifying packages (and potential version constraints) in `requirements/*.in` files and locking those dependencies using [pip-compile-multi](https://pip-compile-multi.readthedocs.io/en/latest/index.html) to produce `requirements/*.txt` files. +Those files are then used by [tox](https://tox.wiki/en/latest/) to create isolated environments and run tests, build docs, etc. + +`tox` can be cumbersome to use for local development. +Therefore `requirements/dev.txt` can be used to create a virtual environment with all dependencies. diff --git a/docs/developer/getting-started.md b/docs/developer/getting-started.md new file mode 100644 index 00000000..14902df5 --- /dev/null +++ b/docs/developer/getting-started.md @@ -0,0 +1,91 @@ +# Getting started + +## Setting up + +### Dependencies + +Development dependencies are specified in `requirements/dev.txt` and can be installed using (see [Dependency Management](./dependency-management.md) for more information) + +```sh +pip install -r requirements/dev.txt +``` + +Additionally, building the documentation requires [pandoc](https://pandoc.org/) which is not on PyPI and needs to be installed through other means, e.g. with your OS package manager. + +### Install the package + +Install the package in editable mode using + +```sh +pip install -e . +``` + +### Set up git hooks + +The CI pipeline runs a number of code formatting and static analysis tools. +If they fail, a build is rejected. +To avoid that, you can run the same tools locally. +This can be done conveniently using [pre-commit](https://pre-commit.com/): + +```sh +pre-commit install +``` + +Alternatively, if you want a different workflow, take a look at ``tox.ini`` or ``.pre-commit.yaml`` to see what tools are run and how. + +## Running tests + +`````{tab-set} +````{tab-item} tox +Run the tests using + +```sh +tox -e py38 +``` + +(or just `tox` if you want to run all environments). + +```` +````{tab-item} Manually +Run the tests using + +```sh +python -m pytest +``` +```` +````` + +## Building the docs + +`````{tab-set} +````{tab-item} tox +Build the documentation using + +```sh +tox -e docs +``` + +This builds the docs and also runs `doctest`. +`linkcheck` can be run separately using + +```sh +tox -e linkcheck +``` +```` + +````{tab-item} Manually + +Build the documentation using + +```sh +python -m sphinx -v -b html -d build/.doctrees docs build/html +``` + +Additionally, test the documentation using + +```sh +python -m sphinx -v -b doctest -d build/.doctrees docs build/html +python -m sphinx -v -b linkcheck -d build/.doctrees docs build/html +``` +```` +````` \ No newline at end of file diff --git a/docs/developer/index.md b/docs/developer/index.md new file mode 100644 index 00000000..23b55441 --- /dev/null +++ b/docs/developer/index.md @@ -0,0 +1,16 @@ +# Developer documentation + +```{include} ../../CONTRIBUTING.md +``` + +## Table of contents + +```{toctree} +--- +maxdepth: 2 +--- + +getting-started +coding-conventions +dependency-management +``` diff --git a/docs/extra_conf.py b/docs/extra_conf.py new file mode 100644 index 00000000..7d4290a1 --- /dev/null +++ b/docs/extra_conf.py @@ -0,0 +1 @@ +x = 1 diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..5329733b --- /dev/null +++ b/docs/index.md @@ -0,0 +1,16 @@ +# Scippnexus + + + An h5py-like utility for NeXus files with seamless Scipp integration +

+ + +```{toctree} +--- +hidden: +--- + +api-reference/index +developer/index +about/index +``` diff --git a/docs/user-guide/test.nxs b/docs/user-guide/test.nxs new file mode 100644 index 0000000000000000000000000000000000000000..272236e7363bdef231f3a46ee7862ee5a7377cf5 GIT binary patch literal 8232 zcmeI1%TB^j5QgWJiqLC>{=UnFeJ^eaN!|&!#OHmTvK?kAqY@6MgKmxk0mej@7?*{%JZs9$S_7WW!F;f^e(Rl*=R%{HDi3naQP}Q z4^M*p%gzxG$Bk9Rr#b6evU+=xO>Vu`LLIB`4(ffe(9NYt@6XfmVfVzZK|4l6+4bD#>fbf}Le}3bbpKbF>YL$QzPy$Lo2`B+2pahhF5>Nt4KnW;;-y&e79Dcjw zhrL0i-k`3)vJh>-Rx_MyVrvVbywLPpFWH_OkD|yc#n34jse1=$1cP%`n!e?(@9HLx z!~WRS4i?rqunywB7iteFW>#bJ^|JXN7psw16(yhqlz=42", - "setuptools_scm[toml]>=6.2", + "setuptools>=68", + "setuptools_scm[toml]>=8.0", ] build-backend = "setuptools.build_meta" +[project] +name = "scippnexus" +description = "An h5py-like utility for NeXus files with seamless Scipp integration" +authors = [{ name = "Scipp contributors" }] +license = { file = "LICENSE" } +readme = "README.md" +classifiers = [ + "Intended Audience :: Science/Research", + "License :: OSI Approved :: BSD License", + "Natural Language :: English", + "Operating System :: OS Independent", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3 :: Only", + "Programming Language :: Python :: 3.8", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Topic :: Scientific/Engineering", + "Typing :: Typed", +] +requires-python = ">=3.8" + +# IMPORTANT: +# Run 'tox -e deps' after making changes here. This will update requirement files. +# Make sure to list one dependency per line. +dependencies = [ + "python-dateutil", + "scipp>=23.07.0", + "scipy", + "h5py", +] + +dynamic = ["version"] + +[project.urls] +"Bug Tracker" = "https://github.com/scipp/scippnexus/issues" +"Source" = "https://github.com/scipp/scippnexus" + [tool.setuptools_scm] [tool.pytest.ini_options] +minversion = "7.0" # The custom `externalfile` marker runs tests that require passwordless # SSH access to login.esss.dk. We do not run it by default. Make sure to # setup keys in your SSH agent before running `pytest -m externalfile`. @@ -33,5 +73,12 @@ skip_gitignore = true profile = "black" [tool.mypy] -mypy_path = "src" +strict = true ignore_missing_imports = true +enable_error_code = [ + "ignore-without-code", + "redundant-expr", + "truthy-bool", +] +show_error_codes = true +warn_unreachable = true diff --git a/requirements/base.in b/requirements/base.in index 9b413654..bc499175 100644 --- a/requirements/base.in +++ b/requirements/base.in @@ -1,4 +1,5 @@ +# Generated by 'tox -e deps', DO NOT EDIT MANUALLY!' python-dateutil -scipp>=23.01.1 +scipp>=23.07.0 scipy -h5py +h5py \ No newline at end of file diff --git a/requirements/base.txt b/requirements/base.txt index ea05094b..5ea0a002 100644 --- a/requirements/base.txt +++ b/requirements/base.txt @@ -1,28 +1,28 @@ -# SHA1:c3c05567d668423130fa3b892cc2cae373423b1c +# SHA1:6c268b2fb8b0add1010c58518a8722d643aef704 # # This file is autogenerated by pip-compile-multi # To update, run: # # pip-compile-multi # -confuse==2.0.0 +confuse==2.0.1 # via scipp graphlib-backport==1.0.3 # via scipp -h5py==3.8.0 +h5py==3.10.0 # via -r base.in -numpy==1.24.1 +numpy==1.24.4 # via # h5py # scipp # scipy python-dateutil==2.8.2 # via -r base.in -pyyaml==6.0 +pyyaml==6.0.1 # via confuse scipp==23.8.0 # via -r base.in -scipy==1.10.0 +scipy==1.10.1 # via -r base.in six==1.16.0 # via python-dateutil diff --git a/requirements/ci.txt b/requirements/ci.txt index 9c45e9bd..0efd86cb 100644 --- a/requirements/ci.txt +++ b/requirements/ci.txt @@ -5,52 +5,52 @@ # # pip-compile-multi # -cachetools==5.3.0 +cachetools==5.3.2 # via tox -certifi==2022.12.7 +certifi==2023.7.22 # via requests -chardet==5.1.0 +chardet==5.2.0 # via tox -charset-normalizer==3.1.0 +charset-normalizer==3.3.1 # via requests colorama==0.4.6 # via tox -distlib==0.3.6 +distlib==0.3.7 # via virtualenv -filelock==3.11.0 +filelock==3.12.4 # via # tox # virtualenv -gitdb==4.0.10 +gitdb==4.0.11 # via gitpython -gitpython==3.1.31 +gitpython==3.1.40 # via -r ci.in idna==3.4 # via requests -packaging==23.1 +packaging==23.2 # via # -r ci.in # pyproject-api # tox -platformdirs==3.2.0 +platformdirs==3.11.0 # via # tox # virtualenv -pluggy==1.0.0 +pluggy==1.3.0 # via tox -pyproject-api==1.5.1 +pyproject-api==1.6.1 # via tox -requests==2.28.2 +requests==2.31.0 # via -r ci.in -smmap==5.0.0 +smmap==5.0.1 # via gitdb tomli==2.0.1 # via # pyproject-api # tox -tox==4.4.12 +tox==4.11.3 # via -r ci.in -urllib3==1.26.15 +urllib3==2.0.7 # via requests -virtualenv==20.21.0 +virtualenv==20.24.6 # via tox diff --git a/requirements/dev.in b/requirements/dev.in new file mode 100644 index 00000000..1c747e48 --- /dev/null +++ b/requirements/dev.in @@ -0,0 +1,10 @@ +-r base.in +-r ci.in +-r docs.in +-r mypy.in +-r static.in +-r test.in +-r wheels.in +jupyterlab +pip-compile-multi +pre-commit diff --git a/requirements/dev.txt b/requirements/dev.txt new file mode 100644 index 00000000..f97d967f --- /dev/null +++ b/requirements/dev.txt @@ -0,0 +1,105 @@ +# SHA1:e3e8cd703eb07e0484bb54fe0e131426d458d1bc +# +# This file is autogenerated by pip-compile-multi +# To update, run: +# +# pip-compile-multi +# +-r base.txt +-r ci.txt +-r docs.txt +-r mypy.txt +-r static.txt +-r test.txt +-r wheels.txt +anyio==4.0.0 + # via jupyter-server +argon2-cffi==23.1.0 + # via jupyter-server +argon2-cffi-bindings==21.2.0 + # via argon2-cffi +arrow==1.3.0 + # via isoduration +async-lru==2.0.4 + # via jupyterlab +cffi==1.16.0 + # via argon2-cffi-bindings +click==8.1.7 + # via + # pip-compile-multi + # pip-tools +fqdn==1.5.1 + # via jsonschema +isoduration==20.11.0 + # via jsonschema +json5==0.9.14 + # via jupyterlab-server +jsonpointer==2.4 + # via jsonschema +jsonschema[format-nongpl]==4.19.1 + # via + # jupyter-events + # jupyterlab-server + # nbformat +jupyter-events==0.8.0 + # via jupyter-server +jupyter-lsp==2.2.0 + # via jupyterlab +jupyter-server==2.9.0 + # via + # jupyter-lsp + # jupyterlab + # jupyterlab-server + # notebook-shim +jupyter-server-terminals==0.4.4 + # via jupyter-server +jupyterlab==4.0.7 + # via -r dev.in +jupyterlab-server==2.25.0 + # via jupyterlab +notebook-shim==0.2.3 + # via jupyterlab +overrides==7.4.0 + # via jupyter-server +pip-compile-multi==2.6.3 + # via -r dev.in +pip-tools==7.3.0 + # via pip-compile-multi +prometheus-client==0.17.1 + # via jupyter-server +pycparser==2.21 + # via cffi +python-json-logger==2.0.7 + # via jupyter-events +rfc3339-validator==0.1.4 + # via + # jsonschema + # jupyter-events +rfc3986-validator==0.1.1 + # via + # jsonschema + # jupyter-events +send2trash==1.8.2 + # via jupyter-server +sniffio==1.3.0 + # via anyio +terminado==0.17.1 + # via + # jupyter-server + # jupyter-server-terminals +toposort==1.10 + # via pip-compile-multi +types-python-dateutil==2.8.19.14 + # via arrow +uri-template==1.3.0 + # via jsonschema +webcolors==1.13 + # via jsonschema +websocket-client==1.6.4 + # via jupyter-server +wheel==0.41.2 + # via pip-tools + +# The following packages are considered to be unsafe in a requirements file: +# pip +# setuptools diff --git a/requirements/docs.txt b/requirements/docs.txt index 249e0dc6..58a3a275 100644 --- a/requirements/docs.txt +++ b/requirements/docs.txt @@ -6,107 +6,116 @@ # pip-compile-multi # -r base.txt +accessible-pygments==0.0.4 + # via pydata-sphinx-theme alabaster==0.7.13 # via sphinx -appdirs==1.4.4 - # via pooch -asttokens==2.2.1 +asttokens==2.4.0 # via stack-data -attrs==22.2.0 - # via jsonschema -babel==2.11.0 - # via sphinx +attrs==23.1.0 + # via + # jsonschema + # referencing +babel==2.13.1 + # via + # pydata-sphinx-theme + # sphinx backcall==0.2.0 # via ipython -beautifulsoup4==4.11.1 +beautifulsoup4==4.12.2 # via # nbconvert # pydata-sphinx-theme -bleach==6.0.0 +bleach==6.1.0 # via nbconvert -certifi==2022.12.7 +certifi==2023.7.22 # via requests -charset-normalizer==3.0.1 +charset-normalizer==3.3.1 # via requests -comm==0.1.2 - # via ipykernel -contourpy==1.0.7 +comm==0.1.4 + # via + # ipykernel + # ipywidgets +contourpy==1.1.1 # via matplotlib -cycler==0.11.0 +cycler==0.12.1 # via matplotlib -debugpy==1.6.6 +debugpy==1.8.0 # via ipykernel decorator==5.1.1 # via ipython defusedxml==0.7.1 # via nbconvert -docutils==0.17.1 +docutils==0.19 # via # nbsphinx # pydata-sphinx-theme # sphinx -entrypoints==0.4 - # via jupyter-client -executing==1.2.0 +executing==2.0.0 # via stack-data -fastjsonschema==2.16.2 +fastjsonschema==2.18.1 # via nbformat -fonttools==4.38.0 +fonttools==4.43.1 # via matplotlib -gitdb==4.0.10 +gitdb==4.0.11 # via gitpython -gitpython==3.1.30 +gitpython==3.1.40 # via -r docs.in idna==3.4 # via requests imagesize==1.4.1 # via sphinx -importlib-metadata==6.0.0 +importlib-metadata==6.8.0 # via + # jupyter-client # nbconvert # sphinx -importlib-resources==5.10.2 - # via jsonschema -ipykernel==6.20.2 +importlib-resources==6.1.0 # via - # -r docs.in - # ipywidgets -ipython==8.8.0 + # jsonschema + # jsonschema-specifications + # matplotlib +ipykernel==6.26.0 + # via -r docs.in +ipython==8.12.3 # via # ipykernel # ipywidgets -ipywidgets==8.0.4 +ipywidgets==8.1.1 # via -r docs.in -jedi==0.18.2 +jedi==0.19.1 # via ipython jinja2==3.1.2 # via # nbconvert # nbsphinx # sphinx -jsonschema==4.17.3 +jsonschema==4.19.1 # via nbformat -jupyter-client==7.4.9 +jsonschema-specifications==2023.7.1 + # via jsonschema +jupyter-client==8.5.0 # via # ipykernel # nbclient -jupyter-core==5.1.5 +jupyter-core==5.4.0 # via + # ipykernel # jupyter-client # nbclient # nbconvert # nbformat jupyterlab-pygments==0.2.2 # via nbconvert -jupyterlab-widgets==3.0.5 +jupyterlab-widgets==3.0.9 # via ipywidgets -kiwisolver==1.4.4 +kiwisolver==1.4.5 # via matplotlib -markupsafe==2.1.2 +markupsafe==2.1.3 # via # jinja2 # nbconvert -matplotlib==3.6.3 +matplotlib==3.7.3 # via # -r docs.in # plopp @@ -114,24 +123,22 @@ matplotlib-inline==0.1.6 # via # ipykernel # ipython -mistune==2.0.4 +mistune==3.0.2 # via nbconvert -nbclient==0.7.2 +nbclient==0.8.0 # via nbconvert -nbconvert==7.2.9 +nbconvert==7.9.2 # via nbsphinx -nbformat==5.7.3 +nbformat==5.9.2 # via # nbclient # nbconvert # nbsphinx -nbsphinx==0.8.12 +nbsphinx==0.9.3 # via -r docs.in -nest-asyncio==1.5.6 - # via - # ipykernel - # jupyter-client -packaging==23.0 +nest-asyncio==1.5.8 + # via ipykernel +packaging==23.2 # via # -r docs.in # ipykernel @@ -148,53 +155,63 @@ pexpect==4.8.0 # via ipython pickleshare==0.7.5 # via ipython -pillow==9.4.0 +pillow==10.1.0 # via matplotlib pkgutil-resolve-name==1.3.10 # via jsonschema -platformdirs==2.6.2 - # via jupyter-core -plopp==23.1.0 +platformdirs==3.11.0 + # via + # jupyter-core + # pooch +plopp==23.10.1 # via -r docs.in -pooch==1.6.0 +pooch==1.8.0 # via -r docs.in -prompt-toolkit==3.0.36 +prompt-toolkit==3.0.39 # via ipython -psutil==5.9.4 +psutil==5.9.6 # via ipykernel ptyprocess==0.7.0 # via pexpect pure-eval==0.2.2 # via stack-data -pydata-sphinx-theme==0.8.1 +pydata-sphinx-theme==0.14.1 # via sphinx-book-theme -pygments==2.14.0 +pygments==2.16.1 # via + # accessible-pygments # ipython # nbconvert + # pydata-sphinx-theme # sphinx -pyparsing==3.0.9 +pyparsing==3.1.1 # via matplotlib -pyrsistent==0.19.3 - # via jsonschema -pytz==2022.7.1 +pytz==2023.3.post1 # via babel -pyzmq==25.0.0 +pyzmq==25.1.1 # via # ipykernel # jupyter-client -requests==2.28.2 +referencing==0.30.2 + # via + # jsonschema + # jsonschema-specifications +requests==2.31.0 # via # -r docs.in # pooch # sphinx -smmap==5.0.0 +rpds-py==0.10.6 + # via + # jsonschema + # referencing +smmap==5.0.1 # via gitdb snowballstemmer==2.2.0 # via sphinx -soupsieve==2.3.2.post1 +soupsieve==2.5 # via beautifulsoup4 -sphinx==4.5.0 +sphinx==6.2.1 # via # -r docs.in # nbsphinx @@ -204,15 +221,15 @@ sphinx==4.5.0 # sphinx-copybutton sphinx-autodoc-typehints==1.18.3 # via -r docs.in -sphinx-book-theme==0.3.3 +sphinx-book-theme==1.0.1 # via -r docs.in -sphinx-copybutton==0.5.1 +sphinx-copybutton==0.5.2 # via -r docs.in sphinxcontrib-applehelp==1.0.4 # via sphinx sphinxcontrib-devhelp==1.0.2 # via sphinx -sphinxcontrib-htmlhelp==2.0.0 +sphinxcontrib-htmlhelp==2.0.1 # via sphinx sphinxcontrib-jsmath==1.0.1 # via sphinx @@ -220,15 +237,15 @@ sphinxcontrib-qthelp==1.0.3 # via sphinx sphinxcontrib-serializinghtml==1.1.5 # via sphinx -stack-data==0.6.2 +stack-data==0.6.3 # via ipython tinycss2==1.2.1 # via nbconvert -tornado==6.2 +tornado==6.3.3 # via # ipykernel # jupyter-client -traitlets==5.8.1 +traitlets==5.12.0 # via # comm # ipykernel @@ -241,17 +258,21 @@ traitlets==5.8.1 # nbconvert # nbformat # nbsphinx -urllib3==1.26.14 +typing-extensions==4.8.0 + # via + # ipython + # pydata-sphinx-theme +urllib3==2.0.7 # via requests -wcwidth==0.2.6 +wcwidth==0.2.8 # via prompt-toolkit webencodings==0.5.1 # via # bleach # tinycss2 -widgetsnbextension==4.0.5 +widgetsnbextension==4.0.9 # via ipywidgets -zipp==3.11.0 +zipp==3.17.0 # via # importlib-metadata # importlib-resources diff --git a/requirements/make_base.py b/requirements/make_base.py new file mode 100644 index 00000000..27a23c2f --- /dev/null +++ b/requirements/make_base.py @@ -0,0 +1,48 @@ +import sys +from argparse import ArgumentParser + +import tomli + +parser = ArgumentParser() +parser.add_argument( + "--nightly", + default="", + help="List of dependencies to install from main branch for nightly tests, " + "separated by commas.", +) +args = parser.parse_args() + +header = "# Generated by 'tox -e deps', DO NOT EDIT MANUALLY!'\n" + +with open("../pyproject.toml", "rb") as toml_file: + pyproject = tomli.load(toml_file) + dependencies = pyproject["project"].get("dependencies") + if not dependencies: + raise RuntimeError("No dependencies found in pyproject.toml") + dependencies = [dep.strip().strip('"') for dep in dependencies] + +with open("base.in", "w") as f: + f.write(header) + f.write("\n".join(dependencies)) + + +def as_nightly(repo: str) -> str: + if "/" in repo: + org, repo = repo.split("/") + else: + org = "scipp" + if repo == "scipp": + version = f"cp{sys.version_info.major}{sys.version_info.minor}" + base = "https://github.com/scipp/scipp/releases/download/nightly/scipp-nightly" + suffix = "manylinux_2_17_x86_64.manylinux2014_x86_64.whl" + return "-".join([base, version, version, suffix]) + return f"{repo} @ git+https://github.com/{org}/{repo}@main" + + +nightly = args.nightly.split(",") if args.nightly else [] +dependencies = [dep for dep in dependencies if not dep.startswith(tuple(nightly))] +dependencies += [as_nightly(arg) for arg in nightly] + +with open("nightly.in", "w") as f: + f.write(header) + f.write("\n".join(dependencies)) diff --git a/requirements/mypy.in b/requirements/mypy.in new file mode 100644 index 00000000..5027d8c3 --- /dev/null +++ b/requirements/mypy.in @@ -0,0 +1,2 @@ +-r test.in +mypy diff --git a/requirements/mypy.txt b/requirements/mypy.txt new file mode 100644 index 00000000..5df22e91 --- /dev/null +++ b/requirements/mypy.txt @@ -0,0 +1,14 @@ +# SHA1:859ef9c15e5e57c6c91510133c01f5751feee941 +# +# This file is autogenerated by pip-compile-multi +# To update, run: +# +# pip-compile-multi +# +-r test.txt +mypy==1.6.1 + # via -r mypy.in +mypy-extensions==1.0.0 + # via mypy +typing-extensions==4.8.0 + # via mypy diff --git a/requirements/nightly.in b/requirements/nightly.in new file mode 100644 index 00000000..609114c2 --- /dev/null +++ b/requirements/nightly.in @@ -0,0 +1,5 @@ +# Generated by 'tox -e deps', DO NOT EDIT MANUALLY!' +python-dateutil +scipy +h5py +https://github.com/scipp/scipp/releases/download/nightly/scipp-nightly-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl \ No newline at end of file diff --git a/requirements/nightly.txt b/requirements/nightly.txt new file mode 100644 index 00000000..fc818bc6 --- /dev/null +++ b/requirements/nightly.txt @@ -0,0 +1,24 @@ +# SHA1:5f33f1f32f89f39e87cf10294ea4a7a49359a308 +# +# This file is autogenerated by pip-compile-multi +# To update, run: +# +# pip-compile-multi +# +graphlib-backport==1.0.3 + # via scipp +h5py==3.10.0 + # via -r nightly.in +numpy==1.24.4 + # via + # h5py + # scipp + # scipy +python-dateutil==2.8.2 + # via -r nightly.in +scipp @ https://github.com/scipp/scipp/releases/download/nightly/scipp-nightly-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl + # via -r nightly.in +scipy==1.10.1 + # via -r nightly.in +six==1.16.0 + # via python-dateutil diff --git a/requirements/static.txt b/requirements/static.txt index 0651b3b4..11418f26 100644 --- a/requirements/static.txt +++ b/requirements/static.txt @@ -5,23 +5,23 @@ # # pip-compile-multi # -cfgv==3.3.1 +cfgv==3.4.0 # via pre-commit -distlib==0.3.6 +distlib==0.3.7 # via virtualenv -filelock==3.9.0 +filelock==3.12.4 # via virtualenv -identify==2.5.15 +identify==2.5.30 # via pre-commit -nodeenv==1.7.0 +nodeenv==1.8.0 # via pre-commit -platformdirs==2.6.2 +platformdirs==3.11.0 # via virtualenv -pre-commit==3.0.0 +pre-commit==3.5.0 # via -r static.in -pyyaml==6.0 +pyyaml==6.0.1 # via pre-commit -virtualenv==20.17.1 +virtualenv==20.24.6 # via pre-commit # The following packages are considered to be unsafe in a requirements file: diff --git a/requirements/test.txt b/requirements/test.txt index 926c2b53..32d7431c 100644 --- a/requirements/test.txt +++ b/requirements/test.txt @@ -6,17 +6,15 @@ # pip-compile-multi # -r base.txt -attrs==22.2.0 - # via pytest -exceptiongroup==1.1.0 +exceptiongroup==1.1.3 # via pytest iniconfig==2.0.0 # via pytest -packaging==23.0 +packaging==23.2 # via pytest -pluggy==1.0.0 +pluggy==1.3.0 # via pytest -pytest==7.2.1 +pytest==7.4.3 # via -r test.in tomli==2.0.1 # via pytest diff --git a/requirements/wheels.txt b/requirements/wheels.txt index 689de3a0..01d277eb 100644 --- a/requirements/wheels.txt +++ b/requirements/wheels.txt @@ -5,11 +5,17 @@ # # pip-compile-multi # -build==0.10.0 +build==1.0.3 # via -r wheels.in -packaging==23.0 +importlib-metadata==6.8.0 + # via build +packaging==23.2 # via build pyproject-hooks==1.0.0 # via build tomli==2.0.1 - # via build + # via + # build + # pyproject-hooks +zipp==3.17.0 + # via importlib-metadata diff --git a/setup.cfg b/setup.cfg index ebcca04d..1ba190c5 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,41 +1,3 @@ -[metadata] -name = scippnexus -author = Scipp contributors (https://github.com/scipp) -description = h5py-like utility for NeXus files based with seamless scipp integration -license = BSD -license_files = LICENSE -long_description = file: README.md -long_description_content_type = text/markdown -url = https://scipp.github.io/scippnexus -project_urls = - Bug Tracker = https://github.com/scipp/scippnexus/issues -classifiers = - Programming Language :: Python :: 3 - Programming Language :: Python :: 3 :: Only - Programming Language :: Python :: 3.8 - Programming Language :: Python :: 3.9 - Programming Language :: Python :: 3.10 - License :: OSI Approved :: BSD License - Operating System :: OS Independent - -[options] -package_dir = - = src -packages = find: -install_requires = - python-dateutil - scipp>=23.07.0 - scipy # we use scipp.interpolate which depends on this - h5py -python_requires = >=3.8 -include_package_data = True - -[options.packages.find] -where = src - -[options.package_data] -scippnexus = py.typed - [flake8] # See https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#line-length max-line-length = 88 diff --git a/src/scippnexus/__init__.py b/src/scippnexus/__init__.py index 72a4e9e7..112e173b 100644 --- a/src/scippnexus/__init__.py +++ b/src/scippnexus/__init__.py @@ -1,6 +1,5 @@ # SPDX-License-Identifier: BSD-3-Clause # Copyright (c) 2023 Scipp contributors (https://github.com/scipp) -# @author Simon Heybrock # flake8: noqa import importlib.metadata diff --git a/tests/package_test.py b/tests/package_test.py new file mode 100644 index 00000000..eefd0e69 --- /dev/null +++ b/tests/package_test.py @@ -0,0 +1,7 @@ +# SPDX-License-Identifier: BSD-3-Clause +# Copyright (c) 2023 Scipp contributors (https://github.com/scipp) +import scippnexus as pkg + + +def test_has_version(): + assert hasattr(pkg, '__version__') diff --git a/tox.ini b/tox.ini index f8aa3a24..52d09ac9 100644 --- a/tox.ini +++ b/tox.ini @@ -8,21 +8,29 @@ setenv = JUPYTER_PLATFORM_DIRS = 1 commands = pytest +[testenv:nightly] +deps = + -r requirements/nightly.txt + pytest +commands = pytest + [testenv:docs] description = invoke sphinx-build to build the HTML docs -basepython = python3.8 -deps = - {posargs:} - -r requirements/docs.txt +deps = -r requirements/docs.txt allowlist_externals=find -setenv = - {[testenv]setenv} - # Search directory for confuse for custom config enabling plopp plotting - SCIPPDIR={toxinidir}{/}docs{/}buildconfig commands = python -m sphinx -j2 -v -b html -d {toxworkdir}/docs_doctrees docs html python -m sphinx -j2 -v -b doctest -d {toxworkdir}/docs_doctrees docs html find html -type f -name "*.ipynb" -not -path "html/_sources/*" -delete +[testenv:releasedocs] +description = invoke sphinx-build to build the HTML docs from a released version +skip_install = true +deps = + scippnexus=={posargs} + {[testenv:docs]deps} +allowlist_externals={[testenv:docs]allowlist_externals} +commands = {[testenv:docs]commands} + [testenv:linkcheck] description = Run Sphinx linkcheck deps = -r requirements/docs.txt @@ -38,9 +46,17 @@ allowlist_externals = sh # either the different formatters can't agree on a format or that static analysis failed. commands = sh -c 'pre-commit run -a || (echo "" && pre-commit run -a)' +[testenv:mypy] +description = Type checking (mypy) +deps = -r requirements/mypy.txt +commands = python -m mypy . + [testenv:deps] description = Update dependencies by running pip-compile-multi -deps = pip-compile-multi +deps = + pip-compile-multi + tomli skip_install = true changedir = requirements -commands = pip-compile-multi -d . +commands = python ./make_base.py --nightly scipp + pip-compile-multi -d . From aaabf9d45f3f1a5e9ebceb8f65c54747be4e65ae Mon Sep 17 00:00:00 2001 From: Simon Heybrock Date: Wed, 25 Oct 2023 09:25:54 +0200 Subject: [PATCH 2/7] Move docs from rst to md --- docs/_static/logo-dark.svg | 87 ++++++ docs/_static/{logo-2022.svg => logo.svg} | 0 docs/_templates/scipp-class-template.rst | 31 -- docs/_templates/scipp-module-template.rst | 66 ----- docs/_templates/sections/header-article.html | 115 -------- docs/about/about.rst | 36 --- docs/about/index.md | 16 +- docs/about/release-notes.rst | 276 ------------------ docs/api-reference/index.md | 96 ++++++ docs/buildconfig/config.yaml | 2 - docs/extra_conf.py | 1 - docs/getting-started/installation.rst | 30 -- docs/index.md | 35 ++- docs/user-guide/classes.rst | 98 ------- docs/user-guide/functions.rst | 10 - docs/user-guide/index.md | 11 + .../quick-start-guide.ipynb | 0 docs/user-guide/test.nxs | Bin 8232 -> 0 bytes 18 files changed, 240 insertions(+), 670 deletions(-) create mode 100644 docs/_static/logo-dark.svg rename docs/_static/{logo-2022.svg => logo.svg} (100%) delete mode 100644 docs/_templates/scipp-class-template.rst delete mode 100644 docs/_templates/scipp-module-template.rst delete mode 100644 docs/_templates/sections/header-article.html delete mode 100644 docs/about/about.rst delete mode 100644 docs/about/release-notes.rst delete mode 100644 docs/buildconfig/config.yaml delete mode 100644 docs/extra_conf.py delete mode 100644 docs/getting-started/installation.rst delete mode 100644 docs/user-guide/classes.rst delete mode 100644 docs/user-guide/functions.rst create mode 100644 docs/user-guide/index.md rename docs/{getting-started => user-guide}/quick-start-guide.ipynb (100%) delete mode 100644 docs/user-guide/test.nxs diff --git a/docs/_static/logo-dark.svg b/docs/_static/logo-dark.svg new file mode 100644 index 00000000..1c0bf70a --- /dev/null +++ b/docs/_static/logo-dark.svg @@ -0,0 +1,87 @@ + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/_static/logo-2022.svg b/docs/_static/logo.svg similarity index 100% rename from docs/_static/logo-2022.svg rename to docs/_static/logo.svg diff --git a/docs/_templates/scipp-class-template.rst b/docs/_templates/scipp-class-template.rst deleted file mode 100644 index 0200267d..00000000 --- a/docs/_templates/scipp-class-template.rst +++ /dev/null @@ -1,31 +0,0 @@ -{{ fullname | escape | underline }} - -.. currentmodule:: {{ module }} - -.. autoclass:: {{ objname }} - :members: - :special-members: __getitem__ - - {% block methods %} - .. automethod:: __init__ - - {% if methods %} - .. rubric:: {{ _('Methods') }} - - .. autosummary:: - {% for item in methods %} - ~{{ name }}.{{ item }} - {%- endfor %} - {% endif %} - {% endblock %} - - {% block attributes %} - {% if attributes %} - .. rubric:: {{ _('Attributes') }} - - .. autosummary:: - {% for item in attributes %} - ~{{ name }}.{{ item }} - {%- endfor %} - {% endif %} - {% endblock %} diff --git a/docs/_templates/scipp-module-template.rst b/docs/_templates/scipp-module-template.rst deleted file mode 100644 index 20e05597..00000000 --- a/docs/_templates/scipp-module-template.rst +++ /dev/null @@ -1,66 +0,0 @@ -{{ fullname | escape | underline}} - -.. automodule:: {{ fullname }} - - {% block attributes %} - {% if attributes %} - .. rubric:: {{ _('Module Attributes') }} - - .. autosummary:: - :toctree: - {% for item in attributes %} - {{ item }} - {%- endfor %} - {% endif %} - {% endblock %} - - {% block functions %} - {% if functions %} - .. rubric:: {{ _('Functions') }} - - .. autosummary:: - :toctree: - {% for item in functions %} - {{ item }} - {%- endfor %} - {% endif %} - {% endblock %} - - {% block classes %} - {% if classes %} - .. rubric:: {{ _('Classes') }} - - .. autosummary:: - :toctree: - :template: scipp-class-template.rst - {% for item in classes %} - {{ item }} - {%- endfor %} - {% endif %} - {% endblock %} - - {% block exceptions %} - {% if exceptions %} - .. rubric:: {{ _('Exceptions') }} - - .. autosummary:: - :toctree: - {% for item in exceptions %} - {{ item }} - {%- endfor %} - {% endif %} - {% endblock %} - -{% block modules %} -{% if modules %} -.. rubric:: Modules - -.. autosummary:: - :toctree: - :template: scipp-module-template.rst - :recursive: -{% for item in modules %} - {{ item }} -{%- endfor %} -{% endif %} -{% endblock %} diff --git a/docs/_templates/sections/header-article.html b/docs/_templates/sections/header-article.html deleted file mode 100644 index b3b9e396..00000000 --- a/docs/_templates/sections/header-article.html +++ /dev/null @@ -1,115 +0,0 @@ -{# To trigger whether the TOC and its button show up #} -{% set page_toc = generate_toc_html() %} - -{# Start copy from buttons.html -#} -{# Utility macros we'll re-use below -#} -{% macro render_tooltip_metadata(tooltip, tooltip_placement) -%} -data-toggle="tooltip" -data-placement="{{ tooltip_placement }}" -title="{{ translate(tooltip) }}" -{%- endmacro %} - - -{% macro render_inner_html(icon, text) %} -{# used across multiple button types #} -{% if icon -%} - - {% if icon.startswith("fa") -%} - - {% else %} - - {% endif -%} - -{% endif %} -{%- if text %}{{ translate(text) }}{% endif -%} -{% endmacro %} - - -{% macro render_link_button(url, tooltip=None, icon=None, text=None, label=None, tooltip_placement="bottom") -%} - - {{ render_inner_html(icon, text) }} - -{% endmacro %} - - -{% macro render_js_button(javascript, tooltip=None, icon=None, text=None, label=None, tooltip_placement="bottom") %} - -{% endmacro %} - - -{% macro render_label_input_button(for_input, tooltip=None, icon=None, text=None, label=None, tooltip_placement="bottom") -%} - -{% endmacro %} - - -{# Modified from original buttons.html to add a text option -#} -{% macro render_button_group(buttons, icon=None, text=None, tooltip=None, label=None) %} -
- -{# Modified from original buttons.html to avoid -75% translation, which makes sense only for icon-only buttons -#} -
-
    - {%- for button in buttons %} -
  • - {{ render_funcs[button.pop("type")](**button) }} -
    • - {% endfor %} -
-
-
-{% endmacro %} - -{%- set render_funcs = { - "group" : render_button_group, - "javascript" : render_js_button, - "link": render_link_button, - "input_label": render_label_input_button, -} --%} -{# End copy from buttons.html -#} - -
-
- {% if theme_single_page != True %} - {{ render_label_input_button(for_input="__navigation", tooltip="Toggle navigation", icon="fas fa-bars", tooltip_placement="right") }} - {% endif %} -
-
- {%- for button in header_buttons -%} - {{ render_funcs[button.pop("type")](**button) }} - {%- endfor -%} - - {% if page_toc -%} - {{ render_label_input_button("__page-toc", icon="fas fa-list", label="page-toc") }} - {%- endif %} -
-
- - -
- {%- if page_toc | length >= 1 %} -
- {{ translate(theme_toc_title) }} -
- - {%- endif %} -
diff --git a/docs/about/about.rst b/docs/about/about.rst deleted file mode 100644 index 8c116876..00000000 --- a/docs/about/about.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. _about: - -About ScippNexus -================ - -Development ------------ - -ScippNexus is an open source project by the `European Spallation Source ERIC `_ (ESS). - -License -------- - -ScippNexus is available as open source under the `BSD-3 license `_. - -Citing ScippNexus ------------------ - -Please cite the following: - -.. image:: https://zenodo.org/badge/475453428.svg - :target: https://zenodo.org/badge/latestdoi/475453428 - -To cite a specific version of ScippNexus, select the desired version on Zenodo to get the corresponding DOI. - -Source code and development ---------------------------- - -ScippNexus is hosted and developed `on GitHub `_. - -Contributing to ScippNexus --------------------------- - -Contributions, bug reports, and ideas are always welcome. -If in doubt whether a feature falls within the scope of ScippNexus please `ask on GitHub `_ before implementing functionality, to reduce the risk of rejected pull requests. -Asking and discussing first is generally always a good idea, since our road map is not very mature at this point. diff --git a/docs/about/index.md b/docs/about/index.md index 9e37d545..c9b59712 100644 --- a/docs/about/index.md +++ b/docs/about/index.md @@ -1,12 +1,20 @@ -# About Scippnexus +# About ScippNexus ## Development -Scippnexus is an open source project by the [European Spallation Source ERIC](https://europeanspallationsource.se/) (ESS). +ScippNexus is an open source project by the [European Spallation Source ERIC](https://europeanspallationsource.se/) (ESS). ## License -Scippnexus is available as open source under the [BSD-3 license](https://opensource.org/licenses/BSD-3-Clause). +ScippNexus is available as open source under the [BSD-3 license](https://opensource.org/licenses/BSD-3-Clause). + +## Citing ScippNexus + +Please cite the following: + +[![DOI](https://zenodo.org/badge/475453428.svg)](https://zenodo.org/badge/latestdoi/475453428) + +To cite a specific version of ScippNeXus select the desired version on Zenodo to get the corresponding DOI. ## Older versions of the documentation @@ -15,4 +23,4 @@ Simply download the archive, unzip and view locally in a web browser. ## Source code and development -Scippnexus is hosted and developed [on GitHub](https://github.com/scipp/scippnexus). +ScippNexus is hosted and developed [on GitHub](https://github.com/scipp/scippnexus). diff --git a/docs/about/release-notes.rst b/docs/about/release-notes.rst deleted file mode 100644 index 6e57a697..00000000 --- a/docs/about/release-notes.rst +++ /dev/null @@ -1,276 +0,0 @@ -.. _release-notes: - -Release Notes -============= - - -.. Template, copy this to create a new section after a release: - - vrelease - -------- - - Features - ~~~~~~~~ - - Breaking changes - ~~~~~~~~~~~~~~~~ - - Bugfixes - ~~~~~~~~ - - Deprecations - ~~~~~~~~~~~~ - -vrelease --------- - -Features -~~~~~~~~ - -Breaking changes -~~~~~~~~~~~~~~~~ - -Bugfixes -~~~~~~~~ - -* Save errors when writing variables using ``create_field`` or ``Group.__setitem__`` `#167 `_. - -Deprecations -~~~~~~~~~~~~ - -v23.08.0 --------- - -Breaking changes -~~~~~~~~~~~~~~~~ - -* ``scippnexus.v2`` is now the default when running ``import scippnexus``. - Legacy interface has moved to ``scippnexus.v1``, but this will be removed in a future release `#158 `_. - -v23.07.0 --------- - -Breaking changes -~~~~~~~~~~~~~~~~ - -* When loading slices, coordinates are no longer converted to attributes but are flagged as unaligned. - This is equivalent to slicing in Scipp since v23.07.0 `#154 `_. - -v23.05.1 --------- - -Bugfixes -~~~~~~~~ - -* Fix loading of data with legacy ``axes`` attribute on signal fields `#145 `_. -* Fix loading of groups with single-valued and unit-less signal field `#145 `_. - -v23.05.0 --------- - -Features -~~~~~~~~ - -* ``scippnexus.v2``: Support NXlog with "sublogs" such as connection_status and alarm `#138 `_. -* ``scippnexus.v2``: Fall back to dim labels from HDF5 if NeXus does not define labels in NXdata and related classes `#139 `_. - -v23.04.1 --------- - -* ``scippnexus.v2``: Fix event selection of length 0 `#137 `_. - -v23.04.0 --------- - -Features -~~~~~~~~ - -* Added the future API of ``scippnexus`` as ``scippnexus.v2``. - For many users the API changes will be minor. - The old API will be deprecated soon and users should try to migrate to the new API. - Note that ``v2`` is not fully stable yet and in particular the behavior in edge cases is subject to change. - -v23.03.0 --------- - -Features -~~~~~~~~ - -* Improve handling of files with legacy ``signal`` and ``axis`` attributes, yielding better dim labels `#108 `_. -* Improve loading and parsing of ``NXoff_geometry`` and ``NXcylindrical_geometry`` `#109 `_. - -Breaking changes -~~~~~~~~~~~~~~~~ - -Bugfixes -~~~~~~~~ - -* Fix issue where subgroups in NXdata-like groups where silently skipped. - This now falls back to loading as ``scipp.DataGroup`` `#108 `_. - -v23.01.0 --------- - -Features -~~~~~~~~ - -* Any NXobject can now be loaded as ``scipp.DataGroup`` `#95 `_. - -Breaking changes -~~~~~~~~~~~~~~~~ - -* :class:`scippnexus.NXevent_data` is now loaded without automatically assigning a variance of 1 to the event weights `#94 `_. -* If an implementation of :class:`scippnexus.NXobject` fails to load (e.g., as a :class:`scipp.DataArray`), the implementation will fall back to a generic load of all datasets in subgroups as a :class:`scipp.DataGroup`. - Previously, this was handled in a variety of cases by simply skipping the offending dataset or group `#95 `_. - -v0.4.2 (November 2022) ----------------------- - -Bugfixes -~~~~~~~~ - -* Fix SASdata to raise an exception when given Q-edges, which is not valid for SASdata `#77 `_. - -Contributors -~~~~~~~~~~~~ - -Simon Heybrock :sup:`a` - -v0.4.1 (November 2022) ----------------------- - -Bugfixes -~~~~~~~~ - -* Fix NXdetetector mechanism for finding dimension labels, which was broken in 0.4.0 in certain cases `#76 `_. - -Contributors -~~~~~~~~~~~~ - -Simon Heybrock :sup:`a` - -v0.4.0 (November 2022) ----------------------- - -Features -~~~~~~~~ - -* Add experimental support for application definitions and customization of loader strategies `#63 `_. - -Contributors -~~~~~~~~~~~~ - -Simon Heybrock :sup:`a` and Jan-Lukas Wynen :sup:`a` - -v0.3.3 (October 2022) ---------------------- - -Bugfixes -~~~~~~~~ - -* Fix :meth:`scippnexus.Field.dims` and :meth:`scippnexus.Field.shape` to consistently return tuples instead of lists `#62 `_. -* Fix :meth:`scippnexus.NXobject.__getitem__` to return children with correctly set up field dimensions when indexed with a class name `#62 `_. - -v0.3.0 (September 2022) ------------------------ - -Features -~~~~~~~~ - -* :class:`scippnexus.NXsource`, :class:`scippnexus.NXsample`, and :class:`scippnexus.NXdisk_chopper` now load all entries `#54 `_. -* :meth:`scippnexus.NXobject.__getitem__` now also accepts :class:`scippnexus.Field` as key and returns all direct children that are NeXus fields, i.e., HDF5 datasets (not groups) `#55 `_. -* :meth:`scippnexus.NXobject.__getitem__` now also accepts a list of classes for selecting multiple child classes `#55 `_. - -Breaking changes -~~~~~~~~~~~~~~~~ - -* :class:`scippnexus.NXsource`, :class:`scippnexus.NXsample`, and :class:`scippnexus.NXdisk_chopper` return a ``dict`` instead of ``scipp.Dataset`` `#54 `_. -* :meth:`scippnexus.Field.__getitem__` now returns a Python object instead of a ``scipp.Variable`` if the field's shape is empty and no unit is given `#57 `_. - -Bugfixes -~~~~~~~~ - -Deprecations -~~~~~~~~~~~~ - -v0.2.1 (August 2022) --------------------- - -Features -~~~~~~~~ - -Breaking changes -~~~~~~~~~~~~~~~~ - -Bugfixes -~~~~~~~~ - -* Improved mechanism to determine dimension labels in ``NXdetector`` which previous resulted in inconsistent behavior `#53 `_. - -Deprecations -~~~~~~~~~~~~ - -Contributors -~~~~~~~~~~~~ - -Simon Heybrock :sup:`a`\ , -Neil Vaytet :sup:`a`\ , -and Jan-Lukas Wynen :sup:`a` - -v0.2.0 (August 2022) --------------------- - -Features -~~~~~~~~ - -* :meth:`scippnexus.NXobject.__getitem__` now accepts classes such as :class:`scippnexus.NXlog` or :class:`scippnexus.NXdata` as key and returns all direct children with an ``NX_class`` attribute matching the provided class `#48 `_. -* Added "dynamic" properties to :class:`scippnexus.NXobject`, to access unique children such as entry or instrument `#49 `_. - -Breaking changes -~~~~~~~~~~~~~~~~ - -* The ``NX_class`` enum has been removed. Use classes such as ``NXlog`` as keys from now on `#48 `_. -* The ``by_nx_class`` method has been removed `#48 `_. - -Bugfixes -~~~~~~~~ - -Contributors -~~~~~~~~~~~~ - -Simon Heybrock :sup:`a` -Neil Vaytet :sup:`a`\ , -and Jan-Lukas Wynen :sup:`a` - -v0.1.3 (June 2022) ------------------- - -Bugfixes -~~~~~~~~ - -* Fixed exception when slicing with single integer (instead of a range) `#36 `_. -* Fixed slicing with bin-edge coords, which previously dropped the upper bound `#36 `_. - -Contributors -~~~~~~~~~~~~ - -Simon Heybrock :sup:`a` - -v0.1.0 (May 2022) ------------------ - -Features -~~~~~~~~ - -This is the initial non-experimental release of scippnexus. - -Contributors -~~~~~~~~~~~~ - -Simon Heybrock :sup:`a`\ , -Neil Vaytet :sup:`a`\ , -and Jan-Lukas Wynen :sup:`a` - -Contributing Organizations --------------------------- -* :sup:`a`\ `European Spallation Source ERIC `_, Sweden diff --git a/docs/api-reference/index.md b/docs/api-reference/index.md index db8f9d85..05265872 100644 --- a/docs/api-reference/index.md +++ b/docs/api-reference/index.md @@ -2,6 +2,82 @@ ## Classes + +### Data Structures + +```{eval-rst} +.. currentmodule:: scippnexus + +.. autosummary:: + :toctree: ../generated/classes + :template: scipp-class-template.rst + :recursive: + + Attrs + Field + File + Group + NXaperture + NXattenuator + NXbeam + NXbeam_stop + NXbending_magnet + NXcapillary + NXcite + NXcollection + NXcollimator + NXcrystal + NXcylindrical_geometry + NXdata + NXdetector + NXdetector_group + NXdetector_module + NXdisk_chopper + NXentry + NXenvironment + NXevent_data + NXfermi_chopper + NXfilter + NXflipper + NXfresnel_zone_plate + NXgeometry + NXgrating + NXguide + NXinsertion_device + NXinstrument + NXlog + NXmirror + NXmoderator + NXmonitor + NXmonochromator + NXnote + NXobject + NXoff_geometry + NXorientation + NXparameters + NXpdb + NXpinhole + NXpolarizer + NXpositioner + NXprocess + NXreflections + NXroot + NXsample + NXsample_component + NXsensor + NXshape + NXslit + NXsource + NXsubentry + NXtransformations + NXtranslation + NXuser + NXvelocity_selector + NXxraylens +``` + +### Exceptions + ```{eval-rst} .. currentmodule:: scippnexus @@ -9,6 +85,23 @@ :toctree: ../generated/classes :template: class-template.rst :recursive: + + NexusStructureError +``` + +### Typing + +```{eval-rst} +.. currentmodule:: scippnexus + +.. autosummary:: + :toctree: ../generated/classes + :template: scipp-class-template.rst + :recursive: + + typing.H5Dataset + typing.H5Group + typing.ScippIndex ``` ## Top-level functions @@ -17,6 +110,9 @@ .. autosummary:: :toctree: ../generated/functions :recursive: + + create_field + create_class ``` ## Submodules diff --git a/docs/buildconfig/config.yaml b/docs/buildconfig/config.yaml deleted file mode 100644 index 0328bb51..00000000 --- a/docs/buildconfig/config.yaml +++ /dev/null @@ -1,2 +0,0 @@ -plot: - use_plopp: true diff --git a/docs/extra_conf.py b/docs/extra_conf.py deleted file mode 100644 index 7d4290a1..00000000 --- a/docs/extra_conf.py +++ /dev/null @@ -1 +0,0 @@ -x = 1 diff --git a/docs/getting-started/installation.rst b/docs/getting-started/installation.rst deleted file mode 100644 index 1d03c316..00000000 --- a/docs/getting-started/installation.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. _installation: - -Installation -============ - -Scippnexus requires Python 3.8 or above. - -Conda ------ - -Packages from `Anaconda Cloud `_ are available for Linux, macOS, and Windows. - -.. code-block:: sh - - conda install -c conda-forge -c scipp scippnexus - -Pip ---- - -Scippnexus is available from `PyPI `_ via ``pip``: - -.. code-block:: sh - - pip install scippnexus - - -See also --------- - -See also the `scipp installation instructions `_ on how to setup a conda environment and how to install additional dependencies such plotting libraries or Jupyter. diff --git a/docs/index.md b/docs/index.md index 5329733b..1d53196e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,15 +1,48 @@ -# Scippnexus +# ScippNexus An h5py-like utility for NeXus files with seamless Scipp integration

+ScippNexus provides a link between the HDF5-based [NeXus Data Format](https://www.nexusformat.org/) and [Scipp](https://scipp.github.io/). +This is possible since NeXus classes (a specification of an HDF5 group and the contained dataset) such as [NXdata](https://manual.nexusformat.org/classes/base_classes/NXdata.html) partially resemble Scipp's [DataArray](https://scipp.github.io/user-guide/data-structures.html#DataArray). + +[h5py](https://docs.h5py.org/en/stable/) is a convenient and powerful tool for accessing groups, datasets, and attributes in an HDF5 file. +However, it operates on a lower level than the NeXus class definitions, which typically treat an entire group as a distinct entity. + +ScippNexus can obviate the need for lengthy low-level code. +It provides an h5py-like API, but applies the paradigm at the NeXus-class level. +This is especially powerful since a number of concepts of Scipp map well to concepts of NeXus: + +- NeXus classes such as NXdata define *dimension scales*, which correspond to *coordinates* in the Scipp terminology. + From a user's point of view we can thus treat an NXdata group in a file as an entity that can be loaded directly into a [scipp.DataArray](https://scipp.github.io/user-guide/data-structures/data-structures.html#DataArray). +- **Labeled dimension** can be used to selectively load slices of an entire NeXus class. + This is modelled after h5py's support for loading slices of datasets but provides the same convenience and safety as [scipp's slicing](https://scipp.github.io/user-guide/slicing.html) by requiring specification of the dimension to slice by its name, rather than plain axis order. +- **Physical units** are stored with most datasets in a NeXus class and are loaded as unit of the [scipp.DataArray](https://scipp.github.io/user-guide/data-structures/data-structures.html#DataArray) values or coordinates. + +## News + +- [August 2023] scippnexus-23.08.0 has been released. + The "v2" API is now the default. +- [April 2023] scippnexus-23.04.0 has been released. + This adds `scippnexus.v2`, which provides the future API of `scippnexus`. + The new API avoids performance bottlenecks when working with small files that contain many groups and datasets. + The new behavior is also more faithful to the file content. + `v2` will become the default in the near future. + +## Get in touch + +- If you have questions that are not answered by these documentation pages, ask on [GitHub discussions](https://github.com/scipp/scippnexus/discussions). + Please include a self-contained reproducible example if possible. +- Report bugs (including unclear, missing, or wrong documentation!), suggest features or view the source code [on GitHub](https://github.com/scipp/scippnexus). + ```{toctree} --- hidden: --- +user-guide/index api-reference/index developer/index about/index diff --git a/docs/user-guide/classes.rst b/docs/user-guide/classes.rst deleted file mode 100644 index bef3683a..00000000 --- a/docs/user-guide/classes.rst +++ /dev/null @@ -1,98 +0,0 @@ -.. currentmodule:: scippnexus - -Classes -======= - -Data Structures ---------------- - -.. autosummary:: - :toctree: ../generated/classes - :template: scipp-class-template.rst - :recursive: - - Attrs - Field - File - Group - NXaperture - NXattenuator - NXbeam - NXbeam_stop - NXbending_magnet - NXcapillary - NXcite - NXcollection - NXcollimator - NXcrystal - NXcylindrical_geometry - NXdata - NXdetector - NXdetector_group - NXdetector_module - NXdisk_chopper - NXentry - NXenvironment - NXevent_data - NXfermi_chopper - NXfilter - NXflipper - NXfresnel_zone_plate - NXgeometry - NXgrating - NXguide - NXinsertion_device - NXinstrument - NXlog - NXmirror - NXmoderator - NXmonitor - NXmonochromator - NXnote - NXobject - NXoff_geometry - NXorientation - NXparameters - NXpdb - NXpinhole - NXpolarizer - NXpositioner - NXprocess - NXreflections - NXroot - NXsample - NXsample_component - NXsensor - NXshape - NXslit - NXsource - NXsubentry - NXtransformations - NXtranslation - NXuser - NXvelocity_selector - NXxraylens - -Exceptions ----------- - -.. autosummary:: - :toctree: ../generated/classes - :template: scipp-class-template.rst - :recursive: - - NexusStructureError - -Typing ------- - -.. currentmodule:: scippnexus - -.. autosummary:: - :toctree: ../generated/classes - :template: scipp-class-template.rst - :recursive: - - typing.H5Dataset - typing.H5Group - typing.ScippIndex diff --git a/docs/user-guide/functions.rst b/docs/user-guide/functions.rst deleted file mode 100644 index 7856f76e..00000000 --- a/docs/user-guide/functions.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. currentmodule:: scippnexus - -Functions -========= - -.. autosummary:: - :toctree: ../generated/functions - - create_field - create_class diff --git a/docs/user-guide/index.md b/docs/user-guide/index.md new file mode 100644 index 00000000..4a8ff59a --- /dev/null +++ b/docs/user-guide/index.md @@ -0,0 +1,11 @@ +# User Guide + +```{toctree} +--- +maxdepth: 2 +--- + +quick-start-guide +nexus-classes +application-definitions +``` diff --git a/docs/getting-started/quick-start-guide.ipynb b/docs/user-guide/quick-start-guide.ipynb similarity index 100% rename from docs/getting-started/quick-start-guide.ipynb rename to docs/user-guide/quick-start-guide.ipynb diff --git a/docs/user-guide/test.nxs b/docs/user-guide/test.nxs deleted file mode 100644 index 272236e7363bdef231f3a46ee7862ee5a7377cf5..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 8232 zcmeI1%TB^j5QgWJiqLC>{=UnFeJ^eaN!|&!#OHmTvK?kAqY@6MgKmxk0mej@7?*{%JZs9$S_7WW!F;f^e(Rl*=R%{HDi3naQP}Q z4^M*p%gzxG$Bk9Rr#b6evU+=xO>Vu`LLIB`4(ffe(9NYt@6XfmVfVzZK|4l6+4bD#>fbf}Le}3bbpKbF>YL$QzPy$Lo2`B+2pahhF5>Nt4KnW;;-y&e79Dcjw zhrL0i-k`3)vJh>-Rx_MyVrvVbywLPpFWH_OkD|yc#n34jse1=$1cP%`n!e?(@9HLx z!~WRS4i?rqunywB7iteFW>#bJ^|JXN7psw16(yhqlz Date: Wed, 25 Oct 2023 09:29:48 +0200 Subject: [PATCH 3/7] Begin fix docs deps --- requirements/docs.in | 14 -------------- 1 file changed, 14 deletions(-) delete mode 100644 requirements/docs.in diff --git a/requirements/docs.in b/requirements/docs.in deleted file mode 100644 index 26e33845..00000000 --- a/requirements/docs.in +++ /dev/null @@ -1,14 +0,0 @@ --r base.in -gitpython -ipykernel -ipywidgets -packaging -plopp -pooch -requests -sphinx -sphinx-autodoc-typehints==1.18.3 # later versions require sphinx >=5 which is incompatible with current sphinx-book-theme -sphinx-book-theme -sphinx-copybutton -matplotlib -nbsphinx From 0ff671a0be6dd53f200417d79f4d47001e8ecf83 Mon Sep 17 00:00:00 2001 From: Simon Heybrock Date: Wed, 25 Oct 2023 09:34:44 +0200 Subject: [PATCH 4/7] Init docs.in from copier --- requirements/docs.in | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 requirements/docs.in diff --git a/requirements/docs.in b/requirements/docs.in new file mode 100644 index 00000000..5d5807a4 --- /dev/null +++ b/requirements/docs.in @@ -0,0 +1,11 @@ +-r base.in +autodoc_pydantic +ipykernel +ipython!=8.7.0 # Breaks syntax highlighting in Jupyter code cells. +myst-parser +nbsphinx +pydata-sphinx-theme>=0.13 +sphinx +sphinx-autodoc-typehints==1.23.0 # Higher versions require sphinx-7, which is not supported by sphinx-design yet +sphinx-copybutton +sphinx-design From 5cd71a49306cbdd9162eab7c571ebabc2836f5da Mon Sep 17 00:00:00 2001 From: Simon Heybrock Date: Wed, 25 Oct 2023 10:05:48 +0200 Subject: [PATCH 5/7] Fix docs --- docs/api-reference/index.md | 1 - docs/index.rst | 77 ------------------- docs/user-guide/application-definitions.ipynb | 6 +- requirements/docs.in | 3 + requirements/docs.txt | 71 ++++++++++------- 5 files changed, 50 insertions(+), 108 deletions(-) delete mode 100644 docs/index.rst diff --git a/docs/api-reference/index.md b/docs/api-reference/index.md index 05265872..3f12151f 100644 --- a/docs/api-reference/index.md +++ b/docs/api-reference/index.md @@ -2,7 +2,6 @@ ## Classes - ### Data Structures ```{eval-rst} diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 62e22bb3..00000000 --- a/docs/index.rst +++ /dev/null @@ -1,77 +0,0 @@ -ScippNexus -========== - -.. raw:: html - - - An h5py-like utility for NeXus files with seamless Scipp integration -

- - -ScippNexus provides a link between the HDF5-based `NeXus Data Format `_ and `scipp `_. -This is possible since NeXus classes (a specification of an HDF5 group and the contained dataset) such as `NXdata `_ partially resemble Scipp's `DataArray `_. - -`h5py `_ is a convenient and powerful tool for accessing groups, datasets, and attributes in an HDF5 file. -However, it operates on a lower level than the NeXus class definitions, which typically treat an entire group as a distinct entity. - -ScippNexus can obviate the need for lengthy low-level code. -It provides an h5py-like API, but applies the paradigm at the NeXus-class level. -This is especially powerful since a number of concepts of Scipp map well to concepts of NeXus: - -- NeXus classes such as NXdata define *dimension scales*, which correspond to *coordinates* in the Scipp terminology. - From a user's point of view we can thus treat an NXdata group in a file as an entity that can be loaded directly into a :class:`scipp.DataArray`. -- **Labeled dimension** can be used to selectively load slices of an entire NeXus class. - This is modelled after h5py's support for loading slices of datasets but provides the same convenience and safety as `scipp's slicing `_ by requiring specification of the dimension to slice by its name, rather than plain axis order. -- **Physical units** are stored with most datasets in a NeXus class and are loaded as unit of the :class:`scipp.DataArray` values or coordinates. - -News ----- - -- [August 2023] scippnexus-23.08.0 has been released. - The "v2" API is now the default. -- [April 2023] scippnexus-23.04.0 has been released. - This adds ``scippnexus.v2``, which provides the future API of ``scippnexus``. - The new API avoids performance bottlenecks when working with small files that contain many groups and datasets. - The new behavior is also more faithful to the file content. - ``v2`` will become the default in the near future. -- [March 2023] scippnexus-23.03.0 has been released. - This brings a number of improvements, including handling of legacy files and loading of geometry information. -- [January 2023] scippnexus-23.01.0 has been released. - This brings support for loading arbitrary groups as :class:`scipp.DataGroup`. - Furthermore, errors are handled in a more transparent way: - ScippNexus will now fall back to returning group contents as a :class:`scipp.DataGroup` instead of silently skipping loading certain fields. -- [November 2022] scippnexus-0.4.0 has been released. - This provides and experimental mechanism for customizing reading and writing of data based on NeXus application definitions. - -Get in touch ------------- - -- If you have questions that are not answered by these documentation pages, ask on `GitHub discussions `_. - Please include a self-contained reproducible example if possible. -- Report bugs (including unclear, missing, or wrong documentation!), suggest features or view the source code `on GitHub `_. - -.. toctree:: - :caption: Getting Started - :hidden: - :maxdepth: 3 - - getting-started/installation - getting-started/quick-start-guide - -.. toctree:: - :caption: User Guide - :hidden: - :maxdepth: 3 - - user-guide/nexus-classes - user-guide/application-definitions - user-guide/classes - user-guide/functions - -.. toctree:: - :caption: About - :hidden: - :maxdepth: 3 - - about/about - about/release-notes diff --git a/docs/user-guide/application-definitions.ipynb b/docs/user-guide/application-definitions.ipynb index f5b84d50..9365e16d 100644 --- a/docs/user-guide/application-definitions.ipynb +++ b/docs/user-guide/application-definitions.ipynb @@ -41,7 +41,7 @@ "source": [ "Definitions provide customization points, e.g., for how ScippNexus can find required information in the HDF5 group, and how contents are mapped to aspects of the returned data (typically a `scipp.DataArray` or `scipp.DataGroup`).\n", "\n", - "Definitions in ScippNexus are subclasses of [NXobject](classes.rst#NXobject).\n", + "Definitions in ScippNexus are subclasses of [NXobject](../generated/classes/scippnexus.NXobject.html#scippnexus.NXobject).\n", "A `definitions` mapping passed to `snx.File` serves as a repository of definitions that `snx.Group` will use when opening a group in a file.\n", "`snx.base_definitions()` is used by default.\n", "The `NX_class` attribute of the HDF5 group is used as a key into the `definitions` mapping.\n", @@ -145,7 +145,9 @@ "source": [ "class MyDataDefinition(snx.NXdata):\n", " def __init__(self, attrs, children):\n", - " super().__init__(attrs=attrs, children=children, fallback_signal_name='mysignal')\n", + " super().__init__(\n", + " attrs=attrs, children=children, fallback_signal_name='mysignal'\n", + " )\n", "\n", "\n", "my_definitions = snx.base_definitions()\n", diff --git a/requirements/docs.in b/requirements/docs.in index 5d5807a4..f3aebbc6 100644 --- a/requirements/docs.in +++ b/requirements/docs.in @@ -9,3 +9,6 @@ sphinx sphinx-autodoc-typehints==1.23.0 # Higher versions require sphinx-7, which is not supported by sphinx-design yet sphinx-copybutton sphinx-design +plopp +pooch +matplotlib diff --git a/requirements/docs.txt b/requirements/docs.txt index 58a3a275..4d02283c 100644 --- a/requirements/docs.txt +++ b/requirements/docs.txt @@ -1,4 +1,4 @@ -# SHA1:0cc3551cc20d9f4c64fd8e9d2b7fb5183e2457ac +# SHA1:f7408a5bf684f2df40f07d7a1b1a3e8a45c0852e # # This file is autogenerated by pip-compile-multi # To update, run: @@ -10,12 +10,16 @@ accessible-pygments==0.0.4 # via pydata-sphinx-theme alabaster==0.7.13 # via sphinx +annotated-types==0.6.0 + # via pydantic asttokens==2.4.0 # via stack-data attrs==23.1.0 # via # jsonschema # referencing +autodoc-pydantic==2.0.1 + # via -r docs.in babel==2.13.1 # via # pydata-sphinx-theme @@ -33,9 +37,7 @@ certifi==2023.7.22 charset-normalizer==3.3.1 # via requests comm==0.1.4 - # via - # ipykernel - # ipywidgets + # via ipykernel contourpy==1.1.1 # via matplotlib cycler==0.12.1 @@ -46,8 +48,9 @@ decorator==5.1.1 # via ipython defusedxml==0.7.1 # via nbconvert -docutils==0.19 +docutils==0.20.1 # via + # myst-parser # nbsphinx # pydata-sphinx-theme # sphinx @@ -57,16 +60,13 @@ fastjsonschema==2.18.1 # via nbformat fonttools==4.43.1 # via matplotlib -gitdb==4.0.11 - # via gitpython -gitpython==3.1.40 - # via -r docs.in idna==3.4 # via requests imagesize==1.4.1 # via sphinx importlib-metadata==6.8.0 # via + # autodoc-pydantic # jupyter-client # nbconvert # sphinx @@ -79,14 +79,13 @@ ipykernel==6.26.0 # via -r docs.in ipython==8.12.3 # via + # -r docs.in # ipykernel - # ipywidgets -ipywidgets==8.1.1 - # via -r docs.in jedi==0.19.1 # via ipython jinja2==3.1.2 # via + # myst-parser # nbconvert # nbsphinx # sphinx @@ -107,10 +106,12 @@ jupyter-core==5.4.0 # nbformat jupyterlab-pygments==0.2.2 # via nbconvert -jupyterlab-widgets==3.0.9 - # via ipywidgets kiwisolver==1.4.5 # via matplotlib +markdown-it-py==3.0.0 + # via + # mdit-py-plugins + # myst-parser markupsafe==2.1.3 # via # jinja2 @@ -123,8 +124,14 @@ matplotlib-inline==0.1.6 # via # ipykernel # ipython +mdit-py-plugins==0.4.0 + # via myst-parser +mdurl==0.1.2 + # via markdown-it-py mistune==3.0.2 # via nbconvert +myst-parser==2.0.0 + # via -r docs.in nbclient==0.8.0 # via nbconvert nbconvert==7.9.2 @@ -140,7 +147,6 @@ nest-asyncio==1.5.8 # via ipykernel packaging==23.2 # via - # -r docs.in # ipykernel # matplotlib # nbconvert @@ -175,8 +181,16 @@ ptyprocess==0.7.0 # via pexpect pure-eval==0.2.2 # via stack-data -pydata-sphinx-theme==0.14.1 - # via sphinx-book-theme +pydantic==2.4.2 + # via + # autodoc-pydantic + # pydantic-settings +pydantic-core==2.10.1 + # via pydantic +pydantic-settings==2.0.3 + # via autodoc-pydantic +pydata-sphinx-theme==0.14.2 + # via -r docs.in pygments==2.16.1 # via # accessible-pygments @@ -186,6 +200,8 @@ pygments==2.16.1 # sphinx pyparsing==3.1.1 # via matplotlib +python-dotenv==1.0.0 + # via pydantic-settings pytz==2023.3.post1 # via babel pyzmq==25.1.1 @@ -198,33 +214,32 @@ referencing==0.30.2 # jsonschema-specifications requests==2.31.0 # via - # -r docs.in # pooch # sphinx rpds-py==0.10.6 # via # jsonschema # referencing -smmap==5.0.1 - # via gitdb snowballstemmer==2.2.0 # via sphinx soupsieve==2.5 # via beautifulsoup4 -sphinx==6.2.1 +sphinx==7.1.2 # via # -r docs.in + # autodoc-pydantic + # myst-parser # nbsphinx # pydata-sphinx-theme # sphinx-autodoc-typehints - # sphinx-book-theme # sphinx-copybutton -sphinx-autodoc-typehints==1.18.3 - # via -r docs.in -sphinx-book-theme==1.0.1 + # sphinx-design +sphinx-autodoc-typehints==1.23.0 # via -r docs.in sphinx-copybutton==0.5.2 # via -r docs.in +sphinx-design==0.5.0 + # via -r docs.in sphinxcontrib-applehelp==1.0.4 # via sphinx sphinxcontrib-devhelp==1.0.2 @@ -250,7 +265,6 @@ traitlets==5.12.0 # comm # ipykernel # ipython - # ipywidgets # jupyter-client # jupyter-core # matplotlib-inline @@ -260,7 +274,10 @@ traitlets==5.12.0 # nbsphinx typing-extensions==4.8.0 # via + # annotated-types # ipython + # pydantic + # pydantic-core # pydata-sphinx-theme urllib3==2.0.7 # via requests @@ -270,8 +287,6 @@ webencodings==0.5.1 # via # bleach # tinycss2 -widgetsnbextension==4.0.9 - # via ipywidgets zipp==3.17.0 # via # importlib-metadata From ac23da5bc2f4cee6c4eb7202341519f28a2d20ea Mon Sep 17 00:00:00 2001 From: SimonHeybrock Date: Wed, 25 Oct 2023 08:07:46 +0000 Subject: [PATCH 6/7] Apply automatic formatting --- src/scippnexus/nxcylindrical_geometry.py | 2 +- src/scippnexus/nxoff_geometry.py | 2 +- src/scippnexus/v1/nxcylindrical_geometry.py | 2 +- src/scippnexus/v1/nxoff_geometry.py | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/scippnexus/nxcylindrical_geometry.py b/src/scippnexus/nxcylindrical_geometry.py index 4e325961..6036f3f8 100644 --- a/src/scippnexus/nxcylindrical_geometry.py +++ b/src/scippnexus/nxcylindrical_geometry.py @@ -14,7 +14,7 @@ def _parse( vertices: sc.Variable, cylinders: sc.Variable, detector_number: Optional[sc.Variable] = None, - parent_detector_number: Optional[sc.Variable] = None + parent_detector_number: Optional[sc.Variable] = None, ) -> sc.Variable: face1_center = cylinders['vertex_index', 0] face1_edge = cylinders['vertex_index', 1] diff --git a/src/scippnexus/nxoff_geometry.py b/src/scippnexus/nxoff_geometry.py index 01a3a358..b483aa56 100644 --- a/src/scippnexus/nxoff_geometry.py +++ b/src/scippnexus/nxoff_geometry.py @@ -15,7 +15,7 @@ def off_to_shape( winding_order: sc.Variable, faces: sc.Variable, detector_faces: Optional[sc.Variable] = None, - detector_number: Optional[sc.Variable] = None + detector_number: Optional[sc.Variable] = None, ) -> sc.Variable: """ Convert OFF shape description to simpler shape representation. diff --git a/src/scippnexus/v1/nxcylindrical_geometry.py b/src/scippnexus/v1/nxcylindrical_geometry.py index 145174c1..46d4e3ce 100644 --- a/src/scippnexus/v1/nxcylindrical_geometry.py +++ b/src/scippnexus/v1/nxcylindrical_geometry.py @@ -13,7 +13,7 @@ def _parse( vertices: sc.Variable, cylinders: sc.Variable, detector_number: Optional[sc.Variable] = None, - parent_detector_number: Optional[sc.Variable] = None + parent_detector_number: Optional[sc.Variable] = None, ) -> sc.Variable: face1_center = cylinders['vertex_index', 0] face1_edge = cylinders['vertex_index', 1] diff --git a/src/scippnexus/v1/nxoff_geometry.py b/src/scippnexus/v1/nxoff_geometry.py index 0e4d550f..654cfc1f 100644 --- a/src/scippnexus/v1/nxoff_geometry.py +++ b/src/scippnexus/v1/nxoff_geometry.py @@ -14,7 +14,7 @@ def off_to_shape( winding_order: sc.Variable, faces: sc.Variable, detector_faces: Optional[sc.Variable] = None, - detector_number: Optional[sc.Variable] = None + detector_number: Optional[sc.Variable] = None, ) -> sc.Variable: """ Convert OFF shape description to simpler shape representation. From 6d8dbb5c53e7d6d8bb3985f796885ca87cc209c3 Mon Sep 17 00:00:00 2001 From: Simon Heybrock Date: Wed, 25 Oct 2023 10:29:29 +0200 Subject: [PATCH 7/7] Update DOI link format --- docs/about/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/about/index.md b/docs/about/index.md index c9b59712..292cafdb 100644 --- a/docs/about/index.md +++ b/docs/about/index.md @@ -12,7 +12,7 @@ ScippNexus is available as open source under the [BSD-3 license](https://opensou Please cite the following: -[![DOI](https://zenodo.org/badge/475453428.svg)](https://zenodo.org/badge/latestdoi/475453428) +[![DOI](https://zenodo.org/badge/475453428.svg)](https://zenodo.org/doi/10.5281/zenodo.7408075) To cite a specific version of ScippNeXus select the desired version on Zenodo to get the corresponding DOI.