From 014524de85f5350d077217868a45133f384bedc3 Mon Sep 17 00:00:00 2001 From: Matthew Evans <7916000+ml-evs@users.noreply.github.com> Date: Mon, 5 Feb 2024 18:20:07 +0100 Subject: [PATCH] Update docs and release workflow (#36) * Tidy up top of docs page * Fix problem where changelog was not being updated on release * Add CHANGELOG to online documentation * Add PyPI release to install instructions * Tidy up docs stubs * Fix formatting of install instructions * Fix changelog link in PyPI metadata * Add favicon --- .github/workflows/release.yml | 8 +- INSTALL.md | 16 +- doc/Makefile | 3 + doc/img/qtoolkit_icon.svg | 10334 +++++++++++++++++++++++++++ doc/source/conf.py | 2 +- doc/source/index.rst | 8 +- doc/source/user/building.rst | 7 - doc/source/user/index.rst | 7 - doc/source/user/quickstart.rst | 12 +- doc/source/user/whatisqtoolkit.rst | 3 +- pyproject.toml | 2 +- 11 files changed, 10358 insertions(+), 44 deletions(-) create mode 100644 doc/img/qtoolkit_icon.svg delete mode 100644 doc/source/user/building.rst diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 4d84b3c..b151ef7 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -42,7 +42,13 @@ jobs: release_branch: ${{ env.PUBLISH_UPDATE_BRANCH }} exclude_labels: "duplicate,question,invalid,wontfix,dependency_updates,skip_changelog" - - name: Update '${{ env.PUBLISH_UPDATE_BRANCH }}' + - name: Configure git and commit CHANGELOG + run: | + git config --global user.email "${GIT_USER_EMAIL}" + git config --global user.name "${GIT_USER_NAME}" + git commit CHANGELOG.md -m "Release ${GITHUB_REF#refs/tags/}" + + - name: Update '${{ env.PUBLISH_UPDATE_BRANCH }}' with automated changes uses: CasperWA/push-protected@v2 with: token: ${{ secrets.RELEASE_PAT_BOT }} diff --git a/INSTALL.md b/INSTALL.md index 2b48ecd..ee51d7c 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,20 +1,20 @@ # Installation -Clone this repository and then install with `pip` in the virtual environment of your choice. +QToolKit is available on [PyPI](https://pypi.org/project/qtoolkit) and can be installed with `pip`: -``` -git clone git@https://github.com:matgenix/qtoolkit -cd qtoolkit -pip install . +```shell +pip install qtoolkit ``` ## Development installation -You can use +Clone this repository and then install with `pip` in the virtual environment of your choice. -``` +```shell +git clone git@https://github.com:matgenix/qtoolkit +cd qtoolkit pip install -e .[dev,tests] ``` -to perform an editable installation with additional development and test dependencies. +This will perform an editable installation with additional development and test dependencies. You can then activate `pre-commit` in your local repository with `pre-commit install`. diff --git a/doc/Makefile b/doc/Makefile index 1b5ac8d..c112ace 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -66,11 +66,14 @@ html: api-doc html-build html-build: generate pandoc --from=markdown --to=rst --output=./source/dev/index.rst ../CONTRIBUTING.md pandoc --from=markdown --to=rst --output=./source/user/install.rst ../INSTALL.md + pandoc --from=markdown --to=rst --output=./source/changelog.rst ../CHANGELOG.md # Re-add rst links from pydata template sed -i -e "1i .. _install:\n" ./source/user/install.rst sed -i -e "1i ..\n THIS FILE IS AUTOMATICALLY GENERATED FROM INSTALL.md\n" ./source/user/install.rst sed -i -e "1i .. _devindex:\n" ./source/dev/index.rst sed -i -e "1i ..\n THIS FILE IS AUTOMATICALLY GENERATED FROM CONTRIBUTING.md\n" ./source/dev/index.rst + sed -i -e "1i .. _changelog:\n" ./source/changelog.rst + sed -i -e "1i ..\n THIS FILE IS AUTOMATICALLY GENERATED FROM CHANGELOG.md\n" ./source/changelog.rst mkdir -p build/html build/doctrees $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html $(FILES) @echo diff --git a/doc/img/qtoolkit_icon.svg b/doc/img/qtoolkit_icon.svg new file mode 100644 index 0000000..0903ee6 --- /dev/null +++ b/doc/img/qtoolkit_icon.svg @@ -0,0 +1,10334 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/source/conf.py b/doc/source/conf.py index 0e39713..06af8e4 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -96,7 +96,7 @@ # # html_theme = 'sphinx_book_theme' html_theme = 'pydata_sphinx_theme' -# html_favicon = '_static/favicon/favicon.ico' +html_favicon = '../img/qtoolkit_icon.svg' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/doc/source/index.rst b/doc/source/index.rst index 389bafd..e152aa5 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -11,16 +11,12 @@ QToolKit documentation User Guide API reference Development + Changelog **Version**: |version| -**Useful links**: -TO BE ADDED - -QToolKit is an interface to most Distributed Resource Management systems, e.g. -SLURM, PBS, ... - +QToolKit is an interface to Distributed Resource Management (DRM) systems, e.g. SLURM and PBS, with the aim to enable programmatic control of queuing systems. .. grid:: 1 2 2 2 diff --git a/doc/source/user/building.rst b/doc/source/user/building.rst deleted file mode 100644 index 93af682..0000000 --- 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 . \ No newline at end of file diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index a80e2e1..877e9f8 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -15,13 +15,6 @@ details are found in :ref:`api`. install quickstart -.. 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 da9978c..fbe0d59 100644 --- a/doc/source/user/quickstart.rst +++ b/doc/source/user/quickstart.rst @@ -4,14 +4,4 @@ QToolKit quickstart =================== -Prerequisites -============= -You need python - -The Basics -========== - -Create an easy script - -ADD OTHER TOPICS: -remote submission, resources, ... \ No newline at end of file +To be added. diff --git a/doc/source/user/whatisqtoolkit.rst b/doc/source/user/whatisqtoolkit.rst index a302ec4..9fdcc98 100644 --- a/doc/source/user/whatisqtoolkit.rst +++ b/doc/source/user/whatisqtoolkit.rst @@ -4,5 +4,4 @@ What is QToolKit? ================= -QToolKit is ... -TODO: add the features that it has. \ No newline at end of file +To be added. diff --git a/pyproject.toml b/pyproject.toml index f7a1c0d..ac55368 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -58,7 +58,7 @@ msonable = ["monty>=2022.9.9",] homepage = "https://matgenix.github.io/qtoolkit/" repository = "https://github.com/matgenix/qtoolkit" documentation = "https://matgenix.github.io/qtoolkit/" -changelog = "https://github.com/matgenix/qtoolkit/CHANGELOG.md" +changelog = "https://matgenix.github.io/qtoolkit/changelog" [tool.setuptools.package-data] qtoolkit = ["py.typed"]