Go Live version

.copier-answers.yml

@@ -1,6 +1,6 @@
 # Changes here will be overwritten by Copier; NEVER EDIT MANUALLY
-_commit: 7a70b18
-_src_path: gh:Matgenix/Matgenix-copier-template
+_commit: d0e6447
+_src_path: [email protected]:Matgenix/Matgenix-copier-template
 author_email: [email protected]
 author_fullname: David Waroquiers
 author_username: davidwaroquiers
@@ -15,3 +15,4 @@ repository_namespace: matgenix
 repository_provider: https://github.com
 short_description: QToolKit is a python wrapper interfacing with job queues (e.g.
     PBS, SLURM, ...).
+

.github/workflows/release.yml

@@ -0,0 +1,89 @@
+name: Publish and Deploy
+
+on:
+  release:
+    types:
+    - published
+
+env:
+  PUBLISH_UPDATE_BRANCH: main
+  GIT_USER_NAME: Matgenix
+  GIT_USER_EMAIL: "[email protected]"
+
+jobs:
+
+  publish:
+    name: Publish package
+    runs-on: ubuntu-latest
+    if: github.repository == 'matgenix/qtoolkit' && startsWith(github.ref, 'refs/tags/v')
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+      with:
+        submodules: true
+        fetch-depth: 0
+
+    - name: Set up Python 3.11
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.11'
+
+    - name: Install Python dependencies
+      run: |
+        python -m pip install -U pip
+        pip install -U setuptools wheel
+        pip install -e .[all]
+
+    - name: Update changelog
+      uses: CharMixer/auto-changelog-action@v1
+      with:
+        token: ${{ secrets.RELEASE_PAT_BOT }}
+        release_branch: ${{ env.PUBLISH_UPDATE_BRANCH }}
+        exclude_labels: "duplicate,question,invalid,wontfix,dependency_updates,skip_changelog"
+
+    - name: Update '${{ env.PUBLISH_UPDATE_BRANCH }}'
+      uses: CasperWA/push-protected@v2
+      with:
+        token: ${{ secrets.RELEASE_PAT_BOT }}
+        branch: ${{ env.PUBLISH_UPDATE_BRANCH }}
+        unprotect_reviews: true
+        sleep: 15
+        force: true
+        tags: true
+
+    - name: Get tagged versions
+      run: echo "PREVIOUS_VERSION=$(git tag -l --sort -version:refname | sed -n 2p)" >> $GITHUB_ENV
+
+    - name: Create release-specific changelog
+      uses: CharMixer/auto-changelog-action@v1
+      with:
+        token: ${{ secrets.RELEASE_PAT_BOT }}
+        release_branch: ${{ env.PUBLISH_UPDATE_BRANCH }}
+        since_tag: "${{ env.PREVIOUS_VERSION }}"
+        output: "release_changelog.md"
+        exclude_labels: "duplicate,question,invalid,wontfix,dependency_updates,skip_changelog"
+
+    - name: Append changelog to release body
+      run: |
+        gh api /repos/${{ github.repository }}/releases/${{ github.event.release.id }} --jq '.body' > release_body.md
+        cat release_changelog.md >> release_body.md
+        gh api /repos/${{ github.repository }}/releases/${{ github.event.release.id }} -X PATCH -F body='@release_body.md'
+      env:
+        GITHUB_TOKEN: ${{ secrets.RELEASE_PAT_BOT }}
+
+    - name: Build source distribution
+      run: python -m build
+
+    - name: Publish package to Test PyPI first
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        user: __token__
+        password: ${{ secrets.TEST_PYPI_PASSWORD }}
+        repository-url: https://test.pypi.org/legacy/
+
+    - name: Publish package to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        user: __token__
+        password: ${{ secrets.PYPI_PASSWORD }}

.github/workflows/testing.yml

@@ -14,7 +14,7 @@ jobs:
 
       - uses: actions/setup-python@v4
         with:
-          python-version: '3.8'
+          python-version: '3.10'
           cache: pip
           cache-dependency-path: pyproject.toml
 
@@ -30,7 +30,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.8', '3.9', '3.10', '3.11']
+        python-version: ['3.9', '3.10', '3.11']
 
     steps:
       - uses: actions/checkout@v3
@@ -49,22 +49,22 @@ jobs:
       - name: Test
         run: pytest --cov=qtoolkit --cov-report=xml
 
-#  docs:
-#    runs-on: ubuntu-latest
-#
-#    steps:
-#      - uses: actions/checkout@v3
-#
-#      - uses: actions/setup-python@v4
-#        with:
-#          python-version: '3.11'
-#          cache: pip
-#          cache-dependency-path: pyproject.toml
-#
-#      - name: Install dependencies
-#        run: |
-#          python -m pip install --upgrade pip
-#          pip install .[strict,docs]
-#
-#      - name: Build
-#        run: jupyter-book build docs --path-output docs_build
+  docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[strict,docs]
+
+      - name: Build
+        run: jupyter-book build docs --path-output docs_build

.gitignore

@@ -69,7 +69,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+doc/_build/
 
 # PyBuilder
 .pybuilder/
@@ -154,3 +154,6 @@ cython_debug/
 
 # PyCharm
 .idea/
+
+# macOS
+.DS_store

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 default_language_version:
   python: python3
-#exclude: '^src/{{ package_name }}/some/directory/'
+exclude: '^doc/'
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v4.4.0
@@ -9,6 +9,7 @@ repos:
   - id: fix-encoding-pragma
     args: [--remove]
   - id: end-of-file-fixer
+    exclude: .copier-answers.yml
   - id: trailing-whitespace
 - repo: https://github.com/myint/autoflake
   rev: v2.0.0
@@ -67,4 +68,4 @@ repos:
   rev: v3.3.1
   hooks:
     - id: pyupgrade
-      args: [--py38-plus]
+      args: [--py39-plus]

CONTRIBUTING.md

@@ -1,7 +1,5 @@
 # Contributing to QToolKit
 
-Full name is Queue Tool Kit
-
 We love your input! We want to make contributing to as easy and
 transparent as possible, whether it's:
 
@@ -64,6 +62,9 @@ We have a few tips for writing good PRs that are accepted into the main repo:
   to python](https://docs.python-guide.org/writing/tests) for some good
   resources on writing good tests.
 - Understand your contributions will fall under the same license as this repo.
+- This project uses `pre-commit` for uniform linting across many developers. You can install
+  it through the extra dev dependencies with `pip install -e .[dev]`  and then run `pre-commit install`
+  to activate it for you local repository.
 
 When you submit your PR, our CI service will automatically run your tests.
 We welcome good discussion on the best ways to write your code, and the comments

INSTALL.md

@@ -0,0 +1,20 @@
+# Installation
+
+Clone this repository and then install with `pip` in the virtual environment of your choice.
+
+```
+git clone git@https://github.com:matgenix/qtoolkit
+cd qtoolkit
+pip install .
+```
+
+## Development installation
+
+You can use
+
+```
+pip install -e .[dev,tests]
+```
+
+to perform an editable installation with additional development and test dependencies.
+You can then activate `pre-commit` in your local repository with `pre-commit install`.

README.md

@@ -1,39 +1,20 @@
 # QToolKit
 
-[![tests](https://img.shields.io/github/actions/workflow/status/matgenix/qtoolkit/testing.yml?branch=main&label=tests)](https://github.com/matgenix/qtoolkit/actions?query=workflow%3Atesting)
+[![tests](https://img.shields.io/github/actions/workflow/status/matgenix/qtoolkit/testing.yml?branch=main&label=tests)](https://github.com/matgenix/qtoolkit/actions/workflows/testing.yml)
 [![code coverage](https://img.shields.io/codecov/c/gh/matgenix/qtoolkit)](https://codecov.io/gh/matgenix/qtoolkit)
 [![pypi version](https://img.shields.io/pypi/v/qtoolkit?color=blue)](https://pypi.org/project/qtoolkit)
 ![supported python versions](https://img.shields.io/pypi/pyversions/qtoolkit)
 
-** [Full Documentation][docs] **
+**[Full Documentation][docs]**
 
-QToolKit is a python software for ... Features of QToolKit include
-
-- Feature A
-- Feature B
-- ...
-
-## Quick start
-
-How to get started.
-
-## Installation
-
-How to install.
-
-## User guide
-
-How to use the software.
+> **Warning**:
+> :construction: This repository is still under construction. :construction:
 
 ## Need help?
 
 Ask questions about QToolKit on the [QToolKit support forum][help-forum].
 If you've found an issue with QToolKit, please submit a bug report on [GitHub Issues][issues].
 
-## Reference
-
-Full reference
-
 ## What’s new?
 
 Track changes to qtoolkit through the [changelog][changelog].
@@ -60,11 +41,12 @@ QToolKit is developed and maintained by Matgenix SRL.
 
 A full list of all contributors can be found [here][contributors].
 
-[help-forum]: https://github.com/materialsproject/atomate2/issues
-[issues]: https://github.com/materialsproject/atomate2/issues
-[installation]: https://matgenix.github.io/qtoolkit/user/install.html
+[help-forum]: https://https://github.com/matgenix/qtoolkit/issues
+[issues]: https://https://github.com/matgenix/qtoolkit/issues
+[installation]: https://https://github.com/matgenix/qtoolkit/blob/main/INSTALL.md
 [contributing]: https://github.com/matgenix/qtoolkit/blob/main/CONTRIBUTING.md
 [codeofconduct]: https://github.com/matgenix/qtoolkit/blob/main/CODE_OF_CONDUCT.md
-[contributors]: https://matgenix.github.io/qtoolkit/about/contributors.html
-[license]: https://raw.githubusercontent.com/matgenix//main/LICENSE
+[changelog]: https://https://github.com/matgenix/qtoolkit/blob/main/CHANGELOG.md
+[contributors]: https://matgenix.github.io/qtoolkit/graphs/contributors
+[license]: https://raw.githubusercontent.com/matgenix/qtoolkit/main/LICENSE
 [docs]: https://matgenix.github.io/qtoolkit/

doc/Makefile

@@ -0,0 +1,72 @@
+# Makefile for Sphinx documentation
+#
+
+# PYVER needs to be major.minor, just "3" doesn't work - it will result in
+# issues with the amendments to PYTHONPATH and install paths (see DIST_VARS).
+
+# Use explicit "version_info" indexing since make cannot handle colon characters, and
+# evaluate it now to allow easier debugging when printing the variable
+
+PYVER:=$(shell python3 -c 'from sys import version_info as v; print("{0}.{1}".format(v[0], v[1]))')
+PYTHON = python$(PYVER)
+
+# You can set these variables from the command line.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= LANG=C sphinx-build
+PAPER         ?=
+# # For merging a documentation archive into a git checkout of numpy/doc
+# # Turn a tag like v1.18.0 into 1.18
+# # Use sed -n -e 's/patttern/match/p' to return a blank value if no match
+# TAG ?= $(shell git describe --tag | sed -n -e's,v\([1-9]\.[0-9]*\)\.[0-9].*,\1,p')
+
+FILES=
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -WT --keep-going -d build/doctrees $(PAPEROPT_$(PAPER)) \
+                  $(SPHINXOPTS) source
+
+.PHONY: help clean html version-check html-build
+
+#------------------------------------------------------------------------------
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  clean     to remove generated doc files and start fresh"
+	@echo "  html      to make standalone HTML files"
+
+clean:
+	-rm -rf build/*
+	find . -name generated -type d -prune -exec rm -rf "{}" ";"
+
+
+#------------------------------------------------------------------------------
+# Automated generation of all documents
+#------------------------------------------------------------------------------
+
+# Build the current QToolKit version, and extract docs from it.
+# We have to be careful of some issues:
+#
+# - Everything must be done using the same Python version
+#
+
+#SPHINXBUILD="LANG=C sphinx-build"
+
+
+#------------------------------------------------------------------------------
+# Basic Sphinx generation rules for different formats
+#------------------------------------------------------------------------------
+generate: build/generate-stamp
+build/generate-stamp: $(wildcard source/reference/*.rst)
+	mkdir -p build
+	touch build/generate-stamp
+
+html: api-doc html-build
+html-build: generate
+	mkdir -p build/html build/doctrees
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html $(FILES)
+	@echo
+	@echo "Build finished. The HTML pages are in build/html."
+api-doc:
+	sphinx-apidoc -e -f -o source/api ../src/qtoolkit