diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 00000000..7cf19205 --- /dev/null +++ b/.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: "dev@matgenix.com" + +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 diff --git a/.github/workflows/testing.yml b/.github/workflows/testing.yml index 77fc5180..815ba1f2 100644 --- a/.github/workflows/testing.yml +++ b/.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 diff --git a/.gitignore b/.gitignore index a80233aa..dcef30d6 100644 --- a/.gitignore +++ b/.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/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 6028ce1a..a5693d97 100644 --- a/CHANGELOG.md +++ b/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 +========= diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 06e783e3..8369ecf5 100644 --- a/CONTRIBUTING.md +++ b/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) diff --git a/INSTALL.md b/INSTALL.md index 2dc2ebf8..cf4f916e 100644 --- a/INSTALL.md +++ b/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 . ``` diff --git a/README.md b/README.md index ef0cd6be..c4d7d86e 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,22 @@ # jobflow-remote -[![tests](https://img.shields.io/github/actions/workflow/status/Matgenix/jobflow_remote/testing.yml?branch=main&label=tests)](https://github.com/Matgenix/jobflow_remote/actions?query=workflow%3Atesting) -[![code coverage](https://img.shields.io/codecov/c/gh/Matgenix/jobflow_remote)](https://codecov.io/gh/Matgenix/jobflow_remote) -[![pypi version](https://img.shields.io/pypi/v/jobflow_remote?color=blue)](https://pypi.org/project/jobflow_remote) -![supported python versions](https://img.shields.io/pypi/pyversions/jobflow_remote) +[![tests](https://img.shields.io/github/actions/workflow/status/Matgenix/jobflow-remote/testing.yml?branch=main&label=tests)](https://github.com/Matgenix/jobflow-remote/actions?query=workflow%3Atesting) +[![code coverage](https://img.shields.io/codecov/c/gh/Matgenix/jobflow-remote)](https://codecov.io/gh/Matgenix/jobflow-remote) +[![pypi version](https://img.shields.io/pypi/v/jobflow-remote?color=blue)](https://pypi.org/project/jobflow-remote) +![supported python versions](https://img.shields.io/pypi/pyversions/jobflow-remote) **[Full Documentation][docs]** -jobflow-remote is a Python package to run jobflow workflows on remote resources. - -## Quick start - -How to get started. - -## Installation - -How to install. - -## User guide - -How to use the software. +Jobflow Remote is a Python package to run [jobflow](https://materialsproject.github.io/jobflow) workflows on remote resources. ## Need help? -Ask questions about jobflow-remote on the [jobflow-remote support forum][help-forum]. +Ask questions about Jobflow Remote on the [Jobflow Remote support forum][help-forum]. If you've found an issue with jobflow-remote, please submit a bug report on [GitHub Issues][issues]. -## Reference - -Full reference - ## What’s new? -Track changes to jobflow_remote through the [changelog][changelog]. +Track changes to jobflow-remote through the [changelog][changelog]. ## Contributing @@ -43,8 +27,9 @@ We maintain a list of all contributors [here][contributors]. ### Code of conduct Help us keep jobflow-remote open and inclusive. -Please read and follow our [Code of Conduct][codeofconduct] -[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md). +Please read and follow our [Code of Conduct][codeofconduct]. + +[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md) ## License diff --git a/doc/Makefile b/doc/Makefile index 0f69cc1a..0d2b1269 100644 --- a/doc/Makefile +++ b/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 diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst index ea34b44c..57b25a9e 100644 --- a/doc/source/api/index.rst +++ b/doc/source/api/index.rst @@ -4,6 +4,4 @@ API Reference ############# -This is the API reference - .. include:: jobflow_remote.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index 759ad05b..9a48c698 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -21,9 +21,9 @@ # -- Project information ----------------------------------------------------- -project = "Jobflow-Remote" +project = "Jobflow Remote" copyright = "2023, Matgenix SRL" -author = "Guido Petretto, David Waroquiers" +author = "Guido Petretto, Matthew Evans, David Waroquiers" import jobflow_remote @@ -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": ( "

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

" ), # "announcement": "

This is still in development

", diff --git a/doc/source/dev/index.rst b/doc/source/dev/index.rst deleted file mode 100644 index 4b7eca16..00000000 --- a/doc/source/dev/index.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _devindex: - -############################## -Contributing to Jobflow-Remote -############################## - -Here are the things that can be done. diff --git a/doc/source/index.rst b/doc/source/index.rst index e4a05105..ca39a51c 100644 --- a/doc/source/index.rst +++ b/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 API reference Development + 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 +`_ 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. +++ diff --git a/doc/source/license.rst b/doc/source/license.rst index 3631a0d9..b85389d3 100644 --- a/doc/source/license.rst +++ b/doc/source/license.rst @@ -1,5 +1,5 @@ ********************** -Jobflow-Remote license +Jobflow Remote license ********************** .. include:: ../../LICENSE diff --git a/doc/source/user/basics.rst b/doc/source/user/basics.rst deleted file mode 100644 index b76a13bd..00000000 --- a/doc/source/user/basics.rst +++ /dev/null @@ -1,11 +0,0 @@ -*************************** -Jobflow-Remote fundamentals -*************************** - -These documents clarify concepts, design decisions, and technical -constraints in Jobflow-Remote. This is a great place to understand the -fundamental Jobflow-Remote ideas and philosophy. - -.. - .. toctree:: - :maxdepth: 1 diff --git a/doc/source/user/building.rst b/doc/source/user/building.rst deleted file mode 100644 index 27837520..00000000 --- a/doc/source/user/building.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _building-from-source: - -Building from source -==================== - -Get the source from the git repository. -Install it with pip install . diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index ec7c92ed..2707d32d 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -1,7 +1,7 @@ .. _user: ######################### -Jobflow-Remote user guide +Jobflow Remote user guide ######################### This guide is an overview and explains the important features; @@ -18,13 +18,6 @@ details are found in :ref:`reference`. tuning states -.. toctree:: - :caption: Advanced usage and interoperability - :maxdepth: 1 - - building - - .. toctree:: :hidden: :caption: Extras diff --git a/doc/source/user/quickstart.rst b/doc/source/user/quickstart.rst index eb17ba61..b734ca83 100644 --- a/doc/source/user/quickstart.rst +++ b/doc/source/user/quickstart.rst @@ -1,7 +1,7 @@ .. _quickstart: ========================= -Jobflow-Remote quickstart +Jobflow Remote quickstart ========================= After completing the :ref:`install`, it is possible to start submitting diff --git a/doc/source/user/troubleshooting.rst b/doc/source/user/troubleshooting.rst deleted file mode 100644 index 396ded4e..00000000 --- a/doc/source/user/troubleshooting.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. _troubleshooting: - -*************** -Troubleshooting -*************** diff --git a/doc/source/user/whatisjobflowremote.rst b/doc/source/user/whatisjobflowremote.rst deleted file mode 100644 index 772bf54d..00000000 --- a/doc/source/user/whatisjobflowremote.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. _whatisjobflowremote: - -======================= -What is Jobflow-Remote? -======================= - -Jobflow-Remote is ... -TODO: add the features that it has. diff --git a/pyproject.toml b/pyproject.toml index d7e32a54..89a6337c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -3,8 +3,8 @@ requires = ["setuptools >= 42", "versioningit ~= 1.0", "wheel"] build-backend = "setuptools.build_meta" [project] -name = "jobflow_remote" -description = "jobflow-remote is a python package to run jobflow workflows on remote resources" +name = "jobflow-remote" +description = "Jobflow Remote is a Python package to run jobflow workflows on remote resources" readme = "README.md" keywords = [] license = { text = "modified BSD" } @@ -64,10 +64,10 @@ strict = [] jf = "jobflow_remote.cli.jf:app" [project.urls] -homepage = "https://Matgenix.github.io/jobflow_remote/" -repository = "https://github.com/Matgenix/jobflow_remote" -documentation = "https://Matgenix.github.io/jobflow_remote/" -changelog = "https://github.com/Matgenix/jobflow_remote/CHANGELOG.md" +homepage = "https://Matgenix.github.io/jobflow-remote/" +repository = "https://github.com/Matgenix/jobflow-remote" +documentation = "https://Matgenix.github.io/jobflow-remote/" +changelog = "https://github.com/Matgenix/jobflow-remote/CHANGELOG.md" [tool.setuptools.package-data] jobflow_remote = ["py.typed"]