Merge pull request nomad-coe#2 from blueraft/add-scaffolding

chore: scaffolding incl ruff, mkdocs

.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.example-format.txt
@@ -38,3 +45,18 @@ jobs:
     - name: Test with nomad
       run: |
         python -m nomad.cli parse tests/data/test.example-format.txt
+  ruff-linting:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: chartboost/ruff-action@v1
+        with:
+          args: "check ."
+  # to enable auto-formatting check, uncomment the following lines below
+  # ruff-formatting:
+  #   runs-on: ubuntu-latest
+  #   steps:
+  #     - uses: actions/checkout@v3
+  #     - uses: chartboost/ruff-action@v1
+  #       with:
+  #         args: "format ."

.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

.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/[email protected]
+        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 }}'

README.md

@@ -25,7 +25,8 @@ 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!**
@@ -47,6 +48,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):
 

docs/assets/.gitignore

@@ -0,0 +1 @@
+nomad-oasis*.zip

docs/explanation/explanation.md

@@ -0,0 +1,4 @@
+# Explanation
+
+!!! note "Attention"
+    Please update the document with relevant information specific to your plugin.

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.

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.
+

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.

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.

docs/index.md

@@ -0,0 +1,50 @@
+# Welcome to the `nomad-parser-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.
+
+<div markdown="block" class="home-grid">
+<div markdown="block">
+
+### Tutorial
+
+A series of tutorials will guide you through the main functionality of `nomad-parser-example`.
+
+- [Tutorial](tutorial/tutorial.md)
+
+</div>
+<div markdown="block">
+
+### 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)
+
+</div>
+
+<div markdown="block">
+
+### Explanation
+
+The explanation [section](explanation/explanation.md) provides background knowledge on this plugin.
+
+</div>
+<div markdown="block">
+
+### 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.
+
+</div>
+</div>

docs/reference/references.md

@@ -0,0 +1,4 @@
+# References
+
+!!! note "Attention"
+    Please update the document with relevant information specific to your plugin.

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;
+}