Added GitHub release workflow and docs builds

.github/workflows/release.yml

@@ -0,0 +1,130 @@
+name: Publish and Deploy
+
+on:
+  release:
+    types:
+    - published
+
+env:
+  PUBLISH_UPDATE_BRANCH: develop
+  GIT_USER_NAME: Matgenix
+  GIT_USER_EMAIL: "[email protected]"
+
+jobs:
+
+  publish:
+    name: Publish package
+    runs-on: ubuntu-latest
+    if: github.repository == 'matgenix/jobflow-remote' && startsWith(github.ref, 'refs/tags/v')
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+      with:
+        submodules: true
+        fetch-depth: 0
+        ref: ${{ env.PUBLISH_UPDATE_BRANCH }}
+
+    - 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: Set git config
+      run: |
+        git config --global user.name "${{ env.GIT_USER_NAME }}"
+        git config --global user.email "${{ env.GIT_USER_EMAIL }}"
+
+    - 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: Install docs dependencies
+      run: |
+        # Required to generate rst files from markdown
+        sudo apt install pandoc
+        pip install .[docs]
+
+    - name: Build Sphinx docs
+      working-directory: doc
+      run: |
+        # cannot use sphinx build directly as the makefile handles generation
+        # of some rst files
+        make html
+
+    - name: Fix permissions # following https://github.com/actions/upload-pages-artifact?tab=readme-ov-file#file-permissions
+      run: |
+        chmod -c -R +rX "./doc/build" | while read line; do
+          echo "::warning title=Invalid file permissions automatically fixed::$line"
+        done
+
+    - name: Upload docs artifact
+      uses: actions/upload-pages-artifact@v2
+      with:
+        path: ./doc/build/html
+
+    - 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: |
+        pip install -U build
+        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/
+
+  deploy_docs:
+    if: github.repository == 'matgenix/jobflow-remote' && startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+    needs: publish
+    environment:
+      name: "Documentation"
+      url: https://matgenix.github.io/Jobflow-Remote
+
+    steps:
+    - name: Deploy docs
+      uses: actions/deploy-pages@v2

.github/workflows/testing.yml

@@ -56,3 +56,34 @@ jobs:
 
       - name: Test
         run: pytest --cov=jobflow_remote --cov-report=xml
+
+  docs:
+    name: Build documentation
+    runs-on: ubuntu-latest
+
+    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 docs dependencies
+      run: |
+        python -m pip install -U pip
+        pip install -U setuptools wheel
+        # Required to generate rst files from markdown
+        sudo apt install pandoc
+        pip install .[docs]
+
+    - name: Build Sphinx docs
+      working-directory: doc
+      run: |
+        # cannot use sphinx build directly as the makefile handles generation
+        # of some rst files
+        make html

.gitignore

@@ -69,7 +69,11 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+doc/_build/
+doc/source/api/*.rst
+
+doc/source/dev/index.rst
+doc/source/changelog.rst
 
 # PyBuilder
 .pybuilder/

CHANGELOG.md

@@ -1,30 +1,2 @@
-Change log
-==========
-
-v0.0.2 (add date)
-------
-
-Lots of improvements and bug fixes this release.
-
-New features:
-
-- New feature 1
-- New feature 2
-- ...
-
-Enhancements:
-
-- Enhancement 1
-- Enhancement 2
-- ...
-
-Bug fixes:
-
-- Bug fix 1
-- Bug fix 2
-- ...
-
-v0.0.1 (add date)
-------
-
-Initial release.
+Changelog
+=========

CONTRIBUTING.md

@@ -14,7 +14,7 @@ transparent as possible, whether it's:
 jobflow-remote is still in development, so at the moment we
 do not have a dedicated help forum. For the time being, please
 submit questions and bugs to the
-[GitHub issues page](https://github.com/Matgenix/jobflow_remote/issues).
+[GitHub issues page](https://github.com/Matgenix/jobflow-remote/issues).
 
 If you are making a bug report, incorporate as many elements of the
 following as possible to ensure a timely response and avoid the
@@ -36,7 +36,7 @@ further tracked.
 
 We use github to host code, to track issues and feature requests,
 as well as accept pull requests. We maintain a list of all
-contributors [here](https://Matgenix.github.io/jobflow_remote/contributors.html).
+contributors [here](https://Matgenix.github.io/jobflow-remote/contributors.html).
 
 Pull requests are the best way to propose changes to the codebase.
 Follow the [Github flow](https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow)

INSTALL.md

@@ -1,10 +1,13 @@
 # Installation
 
+Simple installation instructions can be found below.
+For more advanced setup including configuring a database and runner, please see the [online documentation](https://matgenix.github.io/jobflow-remote/user/install.html)
+
 Clone this repository and then install with `pip` in the virtual environment of your choice.
 
 ```
-git clone git@{{ repository_provider }}:{{ repository_namespace }}/{{ package_name }}
-cd {{package_name}}
+git clone https://github.com/Matgenix/jobflow-remote
+cd jobflow-remote
 pip install .
 ```
 

doc/Makefile

@@ -24,7 +24,7 @@ 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)) \
+ALLSPHINXOPTS   = -T --keep-going -d build/doctrees $(PAPEROPT_$(PAPER)) \
                   $(SPHINXOPTS) source
 
 .PHONY: help clean html version-check html-build
@@ -62,8 +62,21 @@ build/generate-stamp: $(wildcard source/reference/*.rst)
 	mkdir -p build
 	touch build/generate-stamp
 
+generate-rst-from-md:
+	# generate contributing docs
+	mkdir -p source/dev
+	pandoc --from=markdown --to=rst --output=source/dev/_index.rst ../CONTRIBUTING.md
+	echo ".. _devindex:" > source/dev/index.rst
+	cat source/dev/_index.rst >> source/dev/index.rst
+	rm source/dev/_index.rst
+	# generate changelog
+	pandoc --from=markdown --to=rst --output=source/_changelog.rst ../CHANGELOG.md
+	echo ".. _changelog:" > source/changelog.rst
+	cat source/_changelog.rst >> source/changelog.rst
+	rm source/_changelog.rst
+
 html: api-doc html-build
-html-build: generate
+html-build: generate generate-rst-from-md
 	mkdir -p build/html build/doctrees
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html $(FILES)
 	@echo

doc/source/api/index.rst

@@ -4,6 +4,4 @@
 API Reference
 #############
 
-This is the API reference
-
 .. include:: jobflow_remote.rst

doc/source/conf.py

@@ -21,7 +21,7 @@
 
 # -- Project information -----------------------------------------------------
 
-project = "Jobflow-Remote"
+project = "Jobflow Remote"
 copyright = "2023, Matgenix SRL"
 author = "Guido Petretto, David Waroquiers"
 
@@ -54,9 +54,6 @@
     "sphinx.ext.autosummary",
     "sphinx.ext.graphviz",
     "sphinx.ext.ifconfig",
-    "matplotlib.sphinxext.plot_directive",
-    "IPython.sphinxext.ipython_console_highlighting",
-    "IPython.sphinxext.ipython_directive",
     "sphinx.ext.mathjax",
     "sphinx_design",
     "sphinx_copybutton",
@@ -113,7 +110,7 @@
     "collapse_navigation": True,
     "announcement": (
         "<p>"
-        "Jobflow-Remote is still in beta phase. The API may change at any time."
+        "Jobflow Remote is still in beta phase. The API may change at any time."
         "</p>"
     ),
     # "announcement": "<p>This is still in development</p>",

doc/source/index.rst

@@ -1,7 +1,7 @@
 .. _jobflow_remote_docs_mainpage:
 
 ############################
-Jobflow-Remote documentation
+Jobflow Remote documentation
 ############################
 
 .. toctree::
@@ -11,17 +11,14 @@ Jobflow-Remote documentation
    User Guide <user/index>
    API reference <api/index>
    Development <dev/index>
+   Changelog <changelog>
    release
 
 
 **Version**: |version|
 
-**Useful links**:
-TO BE ADDED
-
-Jobflow-Remote is a package to submit jobflow flows remotely.
-
-
+Jobflow Remote is a package to submit `Jobflow
+<https://materialsproject.github.io/jobflow/>`_ flows remotely.
 
 .. grid:: 1 2 2 2
 
@@ -32,7 +29,7 @@ Jobflow-Remote is a package to submit jobflow flows remotely.
         ^^^^^^^^^^^^^^^
 
         If you want to get started quickly, check out our quickstart section.
-        It contains an introduction to Jobflow-Remote's main concepts.
+        It contains an introduction to Jobflow Remote's main concepts.
 
         +++
 
@@ -50,7 +47,7 @@ Jobflow-Remote is a package to submit jobflow flows remotely.
         ^^^^^^^^^^
 
         The user guide provides in-depth information on the
-        key concepts of Jobflow-Remote with useful background information and explanation.
+        key concepts of Jobflow Remote with useful background information and explanation.
 
         +++
 
@@ -68,7 +65,7 @@ Jobflow-Remote is a package to submit jobflow flows remotely.
         ^^^^^^^^^^^^^
 
         The reference guide contains a detailed description of the functions,
-        modules, and objects included in Jobflow-Remote. The reference describes how the
+        modules, and objects included in Jobflow Remote. The reference describes how the
         methods work and which parameters can be used. It assumes that you have an
         understanding of the key concepts.
 
@@ -89,7 +86,7 @@ Jobflow-Remote is a package to submit jobflow flows remotely.
 
         Want to add to the codebase?
         The contributing guidelines will guide you through the
-        process of improving Jobflow-Remote.
+        process of improving Jobflow Remote.
 
         +++
 

doc/source/license.rst

@@ -1,5 +1,5 @@
 **********************
-Jobflow-Remote license
+Jobflow Remote license
 **********************
 
 .. include:: ../../LICENSE