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
Matgenix · Feb 5, 2024 · 014524d · 014524d
1 parent fbd8023
commit 014524d
Show file tree

Hide file tree

Showing 11 changed files with 10,358 additions and 44 deletions.
diff --git 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
@@ -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
@@ -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
diff --git 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
@@ -11,16 +11,12 @@ QToolKit documentation
    User Guide <user/index>
    API reference <api/index>
    Development <dev/index>
+   Changelog <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
diff --git 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
@@ -4,14 +4,4 @@
 QToolKit quickstart
 ===================
 
-Prerequisites
-=============
-You need python
-
-The Basics
-==========
-
-Create an easy script
-
-ADD OTHER TOPICS:
-remote submission, resources, ...
+To be added.
diff --git 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.
+To be added.
diff --git 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"]