merge from main

Author: andre-merzky

.flake8

@@ -36,11 +36,33 @@ max-line-length = 100
 # See https://www.python.org/dev/peps/pep-0008/#should-a-line-break-before-or-after-a-binary-operator
 # for a discussion about the issue and why we disable this.
 
-ignore = B902, D401, D100, W503
+# D205 - "1 blank line required between summary line and description"
+# D400 - "First line should end with a period"
+#
+# Sphinx (autoclass) has three modes of operation when it comes to
+# documenting classes: 'class', 'init', and 'both'. This pertains to how
+# docstrings for the class and init method are handled. Autoclass does
+# not produce a separate text for the class and init methods, but the
+# options above describe where the constructor documentation comes from.
+# This can be either the class docstring (autoclass_content = 'class')
+# or the __init__ docstring or both concatenated. The 'class' options
+# results in empty decriptions for the __init__ parameters. The
+# 'init' option ignores the class docstring, so, in order to get that
+# part into the output, it would need to be duplicated in the __init__
+# docstring. The better option is 'both'. However saying something like
+# "This class..." in the class docstring and "Initializes..." in the
+# __init__ docstring results in awkward phrasing when put together.
+# One can omit the description on the __init__ docstring and simply
+# document the parameters, but then flake8 complains about the
+# structure of the __init__ doctsring. The D205 and D400 errors are
+# precisely those complains. We disable these in order to have a
+# sane way of documenting classes with Sphinx' autoclass.
+
+
+ignore = B902, D205, D400, D401, D100, W503
 
 # D103 - Missing docstring in public function
 #
 # Ignore docstrings requirement in tests
 
 per-file-ignores = tests/*:D103
-

.github/workflows/build-website.yml

@@ -11,6 +11,9 @@ jobs:
       -
         name: Checkout
         uses: actions/checkout@v2
+      -
+        name: Fetch tags
+        run: git fetch --all --tags
       -
         name: Build Website
         run: /bin/bash web/build.sh

.mypy

@@ -17,3 +17,5 @@ ignore_missing_imports = True
 [mypy-pystache.*]
 ignore_missing_imports = True
 
+[mypy-typing_compat.*]
+ignore_missing_imports = True

.readthedocs.yaml

@@ -0,0 +1,21 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+    
+# Set the OS, Python version and other tools you might need
+build:
+    os: ubuntu-22.04
+    tools:
+        python: "3.11"
+
+python:
+    install:
+        - requirements: requirements-docs.txt
+
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+    configuration: docs/conf.py
+    fail_on_warning: true

Makefile

@@ -18,6 +18,11 @@ tests:
 coverage-tests:
 	PYTHONPATH=$(CWD)/src:$(CWD)/tests/plugins1:$(CWD)/tests/plugins2:${PYTHONPATH} \
 		${PYTHON} -m pytest -v --cov $(TESTARGS)
+		
+.PHONY: html-coverage-report
+html-coverage-report:
+	PYTHONPATH=$(CWD)/src:$(CWD)/tests/plugins1:$(CWD)/tests/plugins2:${PYTHONPATH} \
+		${PYTHON} -m pytest -v --cov --cov-report html
 
 .PHONY: verbose-tests
 verbose-tests:
@@ -39,7 +44,7 @@ stylecheck:
 	flake8 src tests
 
 .PHONY: checks
-checks: typecheck stylecheck
+checks: typecheck stylecheck docs
 
 .PHONY: docs
 docs:
@@ -51,7 +56,16 @@ docs:
 .PHONY: web-docs
 web-docs:
 	rm -rf docs/.generated
-	sphinx-build -W -b html -D html_theme='cloud' -D templates_path='_templates' docs docs/.web-build/
+	rm -rf docs/.web-build
+	git fetch --all --tags
+	PSIJ_WEB_DOCS=1 sphinx-multiversion docs docs/.web-build
+	PSIJ_WEB_DOCS=1 sphinx-build --keep-going -n -W -b html docs docs/.web-build/v/dev
+
+.PHONY: web-docs-dev
+web-docs-dev:
+	rm -rf docs/.generated
+	rm -rf docs/.web-build
+	PSIJ_WEB_DOCS=1 sphinx-build --keep-going -n -W -b html docs docs/.web-build/v/dev
 
 .PHONY: style
 style:

QuickStart.md

@@ -1,23 +1,23 @@
 # Quick Start Guide
 
-This document will guide you through the install procedure and your first hello world example.
+This document will guide you through the install procedure and your first Hello World example.
 
 - [Requirements](#requirements)
-- [Install psij](#install-psij)
+- [Install PSI/J](#install-psij)
 - [Hello World example](#hello-world)
 
 ## Requirements
 - python3.7+
 
-## Install psij
+## Install PSI/J
 
-If you have conda installed you might want to start from a fresh environment. This part is not installing psij but setting up a new environment with the specified python version:
+If you have conda installed you might want to start from a fresh environment. This part is not installing PSI/J but setting up a new environment with the specified python version:
 
 1. `conda create -n psij python=3.7`
 2. `conda activate psij`
 
 
-Install psij from the GitHub repository:
+Install PSI/J from the GitHub repository:
 
 1. Clone the repository into your working directory:
 

README-dev.md

@@ -1,6 +1,4 @@
-# Low Level Development Stuff
-
-## Building the Documentation
+# Building the Documentation
 
 There are two ways to build the documentation. One is the plain one, where
 the plain Sphinx output is desired, and the other is the themed version that
@@ -13,7 +11,7 @@ is meant to integrate with the website.
     resulting pages, such as pages being cut off at the bottom. Please use
     a simple http server as detailed below.
 
-### Building the Standalone Documentation
+## Building the Standalone Documentation
 
 1. Make sure you have the documentation dependencies installed:
     ```sh
@@ -28,7 +26,7 @@ is meant to integrate with the website.
 The output will be in `docs/.build`
 
 
-### Building the Themed Documentation
+## Building the Themed Documentation
 
 This builds the themed version of the docs as well as the website. The steps
 are:
@@ -68,19 +66,22 @@ web site. The themed documentation will be found under the "Documentation"
 tab.
 
 
-### Release Process
+## Release Process
 
 Here are the steps for putting out a fresh release to Pypi.
 
 1. Create a new branch from main and make release specific updates:
-    * Update `src/psij/version.py` to the new version number
+    * Update `RELEASE` and `src/psij/version.py` to the new version number
 
 2. Use the standard PR process and get changes from the above step merged to main.
 
 3. Follow instructions here to [pypi docs](https://pypi.org/help/#apitoken) to
    setup tokens on your machine.
 
-4. Run `make VERSION="version string" tag-and-release`. This will:
+4. Make a clean clone of the main branch
+
+5. Run `make VERSION="version string" tag-and-release`, where the version string
+   has the format "x.y.z[-s]". This will:
     * Create and push tags to GitHub.
     * Build the package.
     * Push built package to Pypi.

README-testing.md

@@ -36,6 +36,10 @@ python/cpython-x.y.z`) or something similar, such as loading a conda or
 virtual environment, please run the relevant commands before invoking
 `psij-ci-setup`.
 
+Note: To upload data to the test server, you will need an authentication
+key. You can obtain such a key from https://testing.psij.io/auth.html.
+Obtaining a key requires a valid email.
+
 
 Testing with the CI Runner
 ==========================

RELEASE

@@ -1 +1 @@
-0.1.0.post2
+0.9.0

docs/_static/extras.js

@@ -35,6 +35,13 @@ $(document).ready(function() {
 
         initializeSelectors(selectorType, value);
     });
+    // Sphinx renders attributes differently from properties in that properties
+    // come with a nice "property" prefix in the heading, whereas attributes just
+    // have the name. This hacks the attribute headers to add a "attribute" text
+    // before the attribute name
+    $("dl.attribute > dt.sig").each(function() {
+        $(this).prepend("<em class=\"attribute\"><span class=\"pre\">attribute</span><span class=\"w\"></span></em>");
+    });
 });
 
 function detectAll(selectorType) {
@@ -70,12 +77,19 @@ function detectAll(selectorType) {
         if (text == '"<&' + selectorType + '>"') {
             $(this).addClass(selectorType + "-item").addClass("psij-selector-value");
         }
-        if (text == "executor" && prevSpans.length == 2
-            && prevSpans[0].text() == "execparams" && prevSpans[1].text() == '.') {
+        if (prevSpans.length == 2 && prevSpans[0].text() == "execparams" && prevSpans[1].text() == '.') {
             // remove <span>execparams</span> and <span>.</span>
             prevSpans[0].remove();
             prevSpans[1].remove();
-            $(this).addClass(selectorType + "-item").addClass("psij-selector-value");
+            if (text == "executor") {
+                $(this).addClass(selectorType + "-item").addClass("psij-selector-value");
+            }
+            else if (text == "queue_name") {
+                $(this).text("QUEUE_NAME");
+            }
+            else if (text == "project_name") {
+                $(this).text("PROJECT_NAME");
+            }
         }
         prevSpans.push($(this));
         if (prevSpans.length > 2) {