diff --git a/.github/workflows/actions.yaml b/.github/workflows/actions.yaml index e9edeff..2c9e8de 100644 --- a/.github/workflows/actions.yaml +++ b/.github/workflows/actions.yaml @@ -12,10 +12,17 @@ jobs: - name: Install dependencies run: | pip install --upgrade pip - pip install -r requirements.txt --index-url https://gitlab.mpcdf.mpg.de/api/v4/projects/2187/packages/pypi/simple + pip install '.[dev]' --index-url https://gitlab.mpcdf.mpg.de/api/v4/projects/2187/packages/pypi/simple + pip install coverage coveralls - name: Test with pytest run: | - python -m pytest -sv tests + python -m coverage run -m pytest -sv + - name: Submit to coveralls + continue-on-error: true + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + coveralls --service=github - name: Test with nomad run: | python -m nomad.cli parse tests/data/test.archive.yaml @@ -38,3 +45,17 @@ jobs: - name: Test with nomad run: | python -m nomad.cli parse tests/data/test.archive.yaml + ruff-linting: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: chartboost/ruff-action@v1 + with: + args: "check ." + # ruff-formatting: + # runs-on: ubuntu-latest + # steps: + # - uses: actions/checkout@v3 + # - uses: chartboost/ruff-action@v1 + # with: + # args: "format ." diff --git a/.github/workflows/mkdocs-deploy.yml b/.github/workflows/mkdocs-deploy.yml new file mode 100644 index 0000000..a6c4d41 --- /dev/null +++ b/.github/workflows/mkdocs-deploy.yml @@ -0,0 +1,28 @@ +name: Deploy MkDocs Site + +on: + push: + branches: + - main # Triggers deployment on push to the main branch + +jobs: + deploy: + runs-on: ubuntu-latest + + steps: + - name: Checkout Repository + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: "3.x" + + - name: Install Dependencies + run: | + python -m pip install --upgrade pip + pip install mkdocs mkdocs-material==8.1.1 pymdown-extensions mkdocs-click + + - name: Build and Deploy + run: | + mkdocs gh-deploy --force --remote-branch gh-pages diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 0000000..f7fcff6 --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,84 @@ +# Upload python package to pypi server and github release. +# Reference: https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/ + +name: Upload Python Package + +on: + release: + types: [published] + +jobs: + # publish-to-pypi: + # name: >- + # Publish distribution to PyPI + # runs-on: ubuntu-latest + # environment: + # name: pypi + # url: https://pypi.org/p/nomad-schema-plugin-example + # permissions: + # id-token: write # IMPORTANT: mandatory for trusted publishing + # + # steps: + # - uses: actions/checkout@v4 + # - name: Set up Python + # uses: actions/setup-python@v4 + # with: + # python-version: "3.9" + # - name: Install pypa/build + # run: >- + # python3 -m + # pip install + # build + # --user + # - name: Build a binary wheel and a source tarball + # run: python3 -m build + # - name: Publish distribution to PyPI + # uses: pypa/gh-action-pypi-publish@release/v1 + + github-release: + name: >- + Sign the Python distribution with Sigstore + and upload them to GitHub Release + runs-on: ubuntu-latest + permissions: + contents: write # IMPORTANT: mandatory for making GitHub Releases + id-token: write # IMPORTANT: mandatory for sigstore + + steps: + - uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: "3.9" + - name: Install pypa/build + run: >- + python3 -m + pip install + build + --user + - name: Build a binary wheel and a source tarball + run: python3 -m build + - name: Sign the dists with Sigstore + uses: sigstore/gh-action-sigstore-python@v1.2.3 + with: + inputs: >- + ./dist/*.tar.gz + ./dist/*.whl + - name: Create GitHub Release + env: + GITHUB_TOKEN: ${{ github.token }} + run: >- + gh release create + '${{ github.ref_name }}' + --repo '${{ github.repository }}' + --notes "" + - name: Upload artifact signatures to GitHub Release + env: + GITHUB_TOKEN: ${{ github.token }} + # Upload to GitHub Release using the `gh` CLI. + # `dist/` contains the built packages, and the + # sigstore-produced signatures and certificates. + run: >- + gh release upload + '${{ github.ref_name }}' dist/** + --repo '${{ github.repository }}' diff --git a/README.md b/README.md index ad96bc4..a711deb 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,6 @@ +![](https://github.com/nomad-coe/nomad-schema-plugin-example/actions/workflows/actions.yml/badge.svg) +![](https://coveralls.io/repos/github/nomad-coe/nomad-schema-plugin-example/badge.svg?branch=main) + # NOMAD's schema example plugin ## Getting started @@ -25,13 +28,13 @@ You need at least Python 3.9. ```sh python3 -m venv .pyenv source .pyenv/bin/activate -pip install -r requirements.txt --index-url https://gitlab.mpcdf.mpg.de/api/v4/projects/2187/packages/pypi/simple +pip install --upgrade pip +pip install '.[dev]' --index-url https://gitlab.mpcdf.mpg.de/api/v4/projects/2187/packages/pypi/simple ``` **Note!** Until we have an official pypi NOMAD release with the plugins functionality. Make -sure to include NOMAD's internal package registry (e.g. via `--index-url`). Follow the instructions -in `requirements.txt`. +sure to include NOMAD's internal package registry (e.g. via `--index-url`). ### Run the tests @@ -47,6 +50,20 @@ You can run automated tests with `pytest`: pytest -svx tests ``` +### Run linting + +```sh +ruff check . +``` + +### Run auto-formatting + +This is entirely optional. To add this as a check in github actions pipeline, uncomment the `ruff-formatting` step in `./github/workflows/actions.yaml`. + +```sh +ruff format . +``` + You can parse an example archive that uses the schema with `nomad` (installed via `nomad-lab` Python package): @@ -63,7 +80,6 @@ You can now start to develop you schema. Here are a few things that you might wa - The name of the example section `ExampleSection`. You will also want to define more than one section. - When you change module and class names, make sure to update the `nomad_plugin.yaml` accordingly. - ## Build the python package The `pyproject.toml` file contains everything that is necessary to turn the project @@ -83,8 +99,7 @@ pip install dist/nomad-schema-plugin-example-1.0.tar.gz Read more about python packages, `pyproject.toml`, and how to upload packages to PyPI on the [PyPI documentation](https://packaging.python.org/en/latest/tutorials/packaging-projects/). - ## Next steps To learn more about plugins, how to add them to an Oasis, how to publish them, read our -documentation on plugins: https://nomad-lab.eu/docs/plugins/plugins.html. \ No newline at end of file +documentation on plugins: https://nomad-lab.eu/docs/plugins/plugins.html. diff --git a/docs/assets/.gitignore b/docs/assets/.gitignore new file mode 100644 index 0000000..3881e38 --- /dev/null +++ b/docs/assets/.gitignore @@ -0,0 +1 @@ +nomad-oasis*.zip \ No newline at end of file diff --git a/docs/assets/favicon.png b/docs/assets/favicon.png new file mode 100644 index 0000000..f84c78f Binary files /dev/null and b/docs/assets/favicon.png differ diff --git a/docs/assets/nomad-plugin-logo.png b/docs/assets/nomad-plugin-logo.png new file mode 100644 index 0000000..149856c Binary files /dev/null and b/docs/assets/nomad-plugin-logo.png differ diff --git a/docs/explanation/explanation.md b/docs/explanation/explanation.md new file mode 100644 index 0000000..d4f6235 --- /dev/null +++ b/docs/explanation/explanation.md @@ -0,0 +1,4 @@ +# Explanation + +!!! note "Attention" + Please update the document with relevant information specific to your plugin. diff --git a/docs/how_to/contribute_to_the_documentation.md b/docs/how_to/contribute_to_the_documentation.md new file mode 100644 index 0000000..1234cb7 --- /dev/null +++ b/docs/how_to/contribute_to_the_documentation.md @@ -0,0 +1,4 @@ +# Contribute to the documentation + +!!! note "Attention" + Please update the document with relevant information specific to your plugin. diff --git a/docs/how_to/contribute_to_this_plugin.md b/docs/how_to/contribute_to_this_plugin.md new file mode 100644 index 0000000..4e67d7a --- /dev/null +++ b/docs/how_to/contribute_to_this_plugin.md @@ -0,0 +1,5 @@ +# Contribute to This Plugin + +!!! note "Attention" + Please update the document with relevant information specific to your plugin. + diff --git a/docs/how_to/install_this_plugin.md b/docs/how_to/install_this_plugin.md new file mode 100644 index 0000000..7d0c2ca --- /dev/null +++ b/docs/how_to/install_this_plugin.md @@ -0,0 +1,4 @@ +# Install This Plugin + +!!! note "Attention" + Please update the document with relevant information specific to your plugin. diff --git a/docs/how_to/use_this_plugin.md b/docs/how_to/use_this_plugin.md new file mode 100644 index 0000000..4adc378 --- /dev/null +++ b/docs/how_to/use_this_plugin.md @@ -0,0 +1,10 @@ +# How to Use This Plugin + +This plugin can be used in a NOMAD Oasis instalation.. + +## Add This Plugin to Your NOMAD instalation + +Read the [NOMAD plugin documentation](https://nomad-lab.eu/prod/v1/staging/docs/plugins/plugins.html#add-a-plugin-to-your-nomad) for all details on how to deploy the plugin on your NOMAD instance. + +!!! note "Attention" + Please update the document with relevant information specific to your plugin. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..314cf62 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,50 @@ +# Welcome to the `nomad-schema-plugin-example` documentation + +Short summary about your plugin + +## Introduction + +This is a example plugin. + +!!! note "Attention" + Please update the document with relevant information specific to your plugin. + +
+
+ +### Tutorial + +A series of tutorials will guide you through the main functionality of `nomad-schema-plugin-example`. + +- [Tutorial](tutorial/tutorial.md) + +
+
+ +### How-to guides + +How-to guides provide step-by-step instructions for a wide range of tasks, with the overarching topics: + +- [Install this plugin](how_to/install_this_plugin.md) +- [Use this plugin](how_to/use_this_plugin.md) +- [Contribute to this plugin](how_to/contribute_to_this_plugin.md) +- [Contribute to the documentation](how_to/contribute_to_the_documentation.md) + +
+ +
+ +### Explanation + +The explanation [section](explanation/explanation.md) provides background knowledge on this plugin. + +
+
+ +### Reference + +The reference [section](reference/references.md) includes all CLI commands and arguments, all configuration options, +the possible schema annotations and their arguments, and a glossary of used terms. + +
+
diff --git a/docs/reference/references.md b/docs/reference/references.md new file mode 100644 index 0000000..7d5adf2 --- /dev/null +++ b/docs/reference/references.md @@ -0,0 +1,4 @@ +# References + +!!! note "Attention" + Please update the document with relevant information specific to your plugin. diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 0000000..321e087 --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,69 @@ + +.md-header__button.md-logo :where(img,svg) { + width: 100%; + height: 30px; +} + +.md-header, .md-header__inner { + background-color: #fff; + color: #2A4CDF; +} + +.md-header[data-md-state=shadow] { + box-shadow: 0px 2px 4px -1px rgb(0 0 0 / 20%), 0px 4px 5px 0px rgb(0 0 0 / 14%), 0px 1px 10px 0px rgb(0 0 0 / 12%); + transition: box-shadow 200ms linear; +} + +.md-header__inner { + height: 80px; +} + +.md-header__topic { + font-size: 24px; +} + +.md-footer { + background-color: #2A4CDF; +} + +.md-search__form:hover { + background-color: rgba(0,0,0,.13); +} + +.md-typeset h1 { + color: black; + font-weight: 700; +} + +.youtube { + position: relative; + width: 100%; + height: 0; + padding-bottom: 56.25%; +} + +.youtube iframe { + position: absolute; + top: 0; + left: 0; + width: 100%; + height: 100%; +} + +.home-grid { + display: grid; + grid-template-columns: 1fr 1fr; + grid-column-gap: 24px; + row-gap: 24px; +} + +.home-grid div { + border-radius: 4px; + padding: 24px; + background-color: #f3e9d9; +} + +.home-grid h3 { + margin-top: 0; + font-weight: 700; +} \ No newline at end of file diff --git a/docs/theme/partials/header.html b/docs/theme/partials/header.html new file mode 100644 index 0000000..5b091f3 --- /dev/null +++ b/docs/theme/partials/header.html @@ -0,0 +1,86 @@ +{#- + This file was automatically generated - do not edit +-#} +{% set class = "md-header" %} +{% if "navigation.tabs.sticky" in features %} + {% set class = class ~ " md-header--lifted" %} +{% endif %} +
+ + {% if "navigation.tabs.sticky" in features %} + {% if "navigation.tabs" in features %} + {% include "partials/tabs.html" %} + {% endif %} + {% endif %} +
\ No newline at end of file diff --git a/docs/tutorial/tutorial.md b/docs/tutorial/tutorial.md new file mode 100644 index 0000000..8dc9a99 --- /dev/null +++ b/docs/tutorial/tutorial.md @@ -0,0 +1,4 @@ +# Tutorial + +!!! note "Attention" + Please update the document with relevant information specific to your plugin. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..de1a182 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,57 @@ +site_name: Documentation +site_description: | + The documentation for NOMAD schema plugin example +site_author: The NOMAD Authors +repo_url: https://github.com/nomad-coe/nomad-schema-plugin-example + +nav: + - Home: index.md + - Tutorial: tutorial/tutorial.md + - How-to guides: + - Install this Plugin: how_to/install_this_plugin.md + - Use this Plugin: how_to/use_this_plugin.md + - Contribute to this plugin: how_to/contribute_to_this_plugin.md + - Contribute to the documentation: how_to/contribute_to_the_documentation.md + - Explanation: explanation/explanation.md + - Reference: reference/references.md +plugins: + - search +theme: + name: material + palette: + primary: "#2A4CDF" + accent: "#008A67" + font: + text: "Titillium Web" + logo: assets/nomad-plugin-logo.png + favicon: assets/favicon.png + features: + - navigation.instant + custom_dir: docs/theme +markdown_extensions: + - attr_list + - md_in_html + - admonition + - pymdownx.details + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences + - toc: + permalink: True + - pymdownx.arithmatex: + generic: true + - attr_list + - mkdocs-click + - pymdownx.extra +extra: + generator: false + homepage: https://nomad-lab.eu +use_directory_urls: false +extra_css: + - stylesheets/extra.css +extra_javascript: + - javascript.js + - https://polyfill.io/v3/polyfill.min.js?features=es6 + - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js diff --git a/nomadschemaexample/__init__.py b/nomadschemaexample/__init__.py index b0744dd..23e80ae 100644 --- a/nomadschemaexample/__init__.py +++ b/nomadschemaexample/__init__.py @@ -1 +1 @@ -from .schema import * \ No newline at end of file +from .schema import * diff --git a/nomadschemaexample/schema.py b/nomadschemaexample/schema.py index a5e4667..5f8d3a5 100644 --- a/nomadschemaexample/schema.py +++ b/nomadschemaexample/schema.py @@ -1,18 +1,18 @@ -from nomad.metainfo import Quantity, Package from nomad.datamodel.data import EntryData from nomad.datamodel.metainfo.annotations import ELNAnnotation, ELNComponentEnum +from nomad.metainfo import Package, Quantity m_package = Package() class ExampleSection(EntryData): name = Quantity( - type=str, - a_eln=ELNAnnotation(component=ELNComponentEnum.StringEditQuantity)) + type=str, a_eln=ELNAnnotation(component=ELNComponentEnum.StringEditQuantity) + ) message = Quantity(type=str) def normalize(self, archive, logger): - super(ExampleSection, self).normalize(archive, logger) + super().normalize(archive, logger) logger.info('ExampleSection.normalize called') self.message = f'Hello {self.name}!' diff --git a/pyproject.toml b/pyproject.toml index 8cf1a1b..4cd35e0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -17,9 +17,81 @@ dependencies = [ homepage = "https://github.com/nomad-coe/nomad-schema-example-plugin" [project.optional-dependencies] -tests = [ +dev = [ + 'ruff>=0.2.0', 'pytest' ] + +[tool.ruff] +# Exclude a variety of commonly ignored directories. +exclude = [ + ".bzr", + ".direnv", + ".eggs", + ".git", + ".git-rewrite", + ".hg", + ".mypy_cache", + ".nox", + ".pants.d", + ".pytype", + ".ruff_cache", + ".svn", + ".tox", + ".venv", + "__pypackages__", + "_build", + "buck-out", + "build", + "dist", + "node_modules", + "venv", +] + +# Same as Black. +line-length = 88 +indent-width = 4 + +# Assume Python 3.9 +target-version = "py39" + +[tool.ruff.lint] +select = [ + # pycodestyle + "E", + # Pyflakes + "F", + # pyupgrade + "UP", + # isort + "I", + # pylint + "PL" +] + +ignore = [ + "F403", # 'from module import *' used; unable to detect undefined names +] + +fixable = ["ALL"] + +# Allow unused variables when underscore-prefixed. +dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$" + +# this is entirely optional, you can remove this if you wish to +[tool.ruff.format] +# use single quotes for strings. +quote-style = "single" + +# indent with spaces, rather than tabs. +indent-style = "space" + +# Like Black, respect magic trailing commas. +skip-magic-trailing-comma = false + +# Like Black, automatically detect the appropriate line ending. +line-ending = "auto" + [tool.setuptools.packages.find] include = ["nomadschemaexample*"] diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index 1a31d8e..0000000 --- a/requirements.txt +++ /dev/null @@ -1,8 +0,0 @@ -# This is not yet an official pypi release. You need to add our gitlab package registry -# when running pip install: -# pip install -r requirements.txt --index-url https://gitlab.mpcdf.mpg.de/api/v4/projects/2187/packages/pypi/simple -nomad-lab>=1.2.0 -# To build a nomad-lab package from a regular clone of nomad-fair -# run "python -m build --sdist". Point to the resulting file here, e.g.: -# ../../../dist/nomad-lab-1.2.0.dev98+g5b6b0745a.d20230330.tar.gz -pytest \ No newline at end of file diff --git a/tests/test_schema.py b/tests/test_schema.py index 24ceaeb..6c571b0 100644 --- a/tests/test_schema.py +++ b/tests/test_schema.py @@ -1,5 +1,7 @@ import os.path -from nomad.client import parse, normalize_all + +from nomad.client import normalize_all, parse + def test_schema(): test_file = os.path.join(os.path.dirname(__file__), 'data', 'test.archive.yaml')