Merge pull request '2022.6.8 - Dokumentation' (#87) from 2022.6.8 into 2022.6

Reviewed-on: #87
Closes #56

README.md

@@ -13,6 +13,7 @@
 ## Table of Contents
 <!-- TABLE OF CONTENTS -->
 <ol>
+   <li><a href="#Features">Features</a></li>
    <li>
      <a href="#getting-started">Getting Started</a>
      <ul>
@@ -26,6 +27,52 @@
    <li><a href="#contact">Contact</a></li>
 </ol>
 
+## Features
+<!-- FEATURE OVERVIEW -->
+- Expandle
+- Application base
+    - Standardized application classes
+    - Application object builder
+    - Application extension classes
+    - Startup classes
+    - Startup extension classes
+- Configuration
+    - Configure via object mapped JSON
+    - Console argument handling
+- Console class for in and output
+    - Banner
+    - Spinner
+    - Options (menu)
+    - Table
+    - Write
+    - Write_at
+    - Write_line
+    - Write_line_at
+- Dependency injection
+    - Service lifetimes: singleton, scoped and transient
+- Providing of application environment
+    - Environment (development, staging, testing, production)
+    - Appname
+    - Customer
+    - Hostname
+    - Runtime directory
+    - Working directory
+- Logging
+    - Standardized logger
+    - Log-level (FATAL, ERROR, WARN, INFO, DEBUG & TRACE)
+- Mail handling
+    - Send mails
+- Pipe classes
+    - Convert input
+- Utils
+    - Credential manager
+        - Encryption via BASE64
+    - PIP wrapper class based on subprocess
+        - Run pip commands
+    - String converter to different variants
+        - to_lower_case
+        - to_camel_case
+        - ...
 
 <!-- GETTING STARTED -->
 ## Getting Started

cpl-workspace.json

@@ -23,7 +23,7 @@
       "set-pip-urls": "cpl run set-pip-urls $ARGS; echo '';",
 
       "docs-build": "echo 'Build Documentation'; cd docs/; sphinx-apidoc -o source/ ../src/cpl_core; sphinx-apidoc -o source/ ../src/cpl_query; make clean; make html; rm source/cpl_query.tests.rst;",
-      "db": "cpl build-docs",
+      "db": "cpl docs-build",
       "docs-open": "xdg-open $PWD/docs/build/html/index.html &",
       "do": "cpl docs-open",
 
@@ -87,8 +87,8 @@
 
       "dev-install": "cpl di-core; cpl di-cli; cpl di-query;",
       "di": "cpl dev-install",
-      "di-core": "pip install cpl-query --pre --upgrade --extra-index-url https://pip-dev.sh-edraft.de",
-      "di-cli": "pip install cpl-query --pre --upgrade --extra-index-url https://pip-dev.sh-edraft.de",
+      "di-core": "pip install cpl-core --pre --upgrade --extra-index-url https://pip-dev.sh-edraft.de",
+      "di-cli": "pip install cpl-cli --pre --upgrade --extra-index-url https://pip-dev.sh-edraft.de",
       "di-query": "pip install cpl-query --pre --upgrade --extra-index-url https://pip-dev.sh-edraft.de"
     }
   }

docs/build/html/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 8170277cf12e5442e6180427108a8adf
+config: 9ea51a00cf3559575c97b7efd7a002e5
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/build/html/_sources/cli.add.md.txt

@@ -20,6 +20,12 @@ If you call the command in a CPL workspace, you can use the project names. Other
 ## Arguments
 
 | Argument               |                        Description                         | Value type |
-| ------------------------- |:---------------------------------------------------------------:|:----------------:|
-| ```<source-project>```    | Name of the project to which the reference has to be added      | ```str```
-| ```<target-project>```    | Name of the project to be referenced                            | ```str```
+|------------------------|:----------------------------------------------------------:|:----------:|
+| ```<source-project>``` | Name of the project to which the reference has to be added | ```str```  |
+| ```<target-project>``` |            Name of the project to be referenced            | ```str```  |
+
+## Flags
+
+| Argument         |                Description                 |
+|------------------|:------------------------------------------:|
+| ```--simulate``` | Specifies whether the command is simulated |

docs/build/html/_sources/cli.generate.md.txt

@@ -26,10 +26,13 @@ Generates files based on a schematic.
 ## Schematics
 
 | Schematic       |              Description              |  Arguments   |
-| ----------------- |:-------------------:|:----------------:|
-| ```abc```         | Abstract base class | ```<name>```
-| ```class```       | Class               | ```<name>```
-| ```enum```        | Enum class          | ```<name>```
-| ```service```     | Service class       | ```<name>```
-| ```settings```    | [Configmodel](cpl_core.configuration) | ```<name>```
-| ```thread```      | Thread class        | ```<name>```
+|-----------------|:-------------------------------------:|:------------:|
+| ```abc```       |          Abstract base class          | ```<name>``` |
+| ```class```     |                 Class                 | ```<name>``` |
+| ```enum```      |              Enum class               | ```<name>``` |
+| ```pipe```      |              Pipe class               | ```<name>``` |
+| ```service```   |             Service class             | ```<name>``` |
+| ```settings```  | [Configmodel](cpl_core.configuration) | ```<name>``` |
+| ```test```      |              Test class               | ```<name>``` |
+| ```thread```    |             Thread class              | ```<name>``` |
+| ```validator``` |            Validator class            | ```<name>``` |

docs/build/html/_sources/cli.install.md.txt

@@ -19,5 +19,13 @@ Without given package it will install the depedencies of the CPL project your in
 ## Arguments
 
 | Argument        |      Description       | Value type |
-| ----------------- |:-----------------------------:|:-------------:|
+|-----------------|:----------------------:|:----------:|
 | ```<package>``` | The package to install | ```str```  |
+
+## Flags
+
+| Argument         |                     Description                      |
+|------------------|:----------------------------------------------------:|
+| ```--dev```      | Specifies whether the command is in development mode |
+| ```--virtual```  |    Specifies whether the command is virtual mode     |
+| ```--simulate``` |      Specifies whether the command is simulated      |

docs/build/html/_sources/cli.new.md.txt

@@ -19,13 +19,24 @@ Generates a workspace and initial project or add a project to workspace.
 If the command is running in a CPL workspace, it will add the new project to the workspace.
 
 | Argument     |                     Description                      | Value type |
-| ----------------- |:-----------------------------------------------------:|:-------------:|
+|--------------|:----------------------------------------------------:|:----------:|
 | ```<type>``` | The type of the project, see [types](#project-types) | ```str```  |
 | ```<name>``` |               The name of the project                | ```str```  |
 
 ## Project types
 
 | Project type  |         Description          |
-| ----------------- |:-----------------------------:|
+|---------------|:----------------------------:|
 | ```console``` | A simple console application |
 | ```library``` |          A package           |
+
+## Flags
+
+| Argument                  |                 Description                 |
+|---------------------------|:-------------------------------------------:|
+| ```--async```             |       Specifies whether async is used       |
+| ```--application-base```  | Specifies whether application base is used  |
+| ```--startup```           |      Specifies whether startup is used      |
+| ```--service-providing``` | Specifies whether service-providing is used |
+| ```--nothing```           |      Specifies whether nothing is used      |
+| ```--venv```              |       Specifies whether venv is used        |

docs/build/html/_sources/cli.remove.md.txt

@@ -20,5 +20,11 @@ If you call the command in a CPL workspace, you can use the project names. Other
 ## Arguments
 
 | Argument        |            Description            | Value type |
-| ------------------------- |:-------------------------------------:|:----------------:|
-| ```<project>```           | The name of the project to delete     | ```str```
+|-----------------|:---------------------------------:|:----------:|
+| ```<project>``` | The name of the project to delete | ```str```  |
+
+## Flags
+
+| Argument         |                     Description                      |
+|------------------|:----------------------------------------------------:|
+| ```--simulate``` |      Specifies whether the command is simulated      |

docs/build/html/_sources/cli.uninstall.md.txt

@@ -18,5 +18,13 @@ Uninstall given package from project via pip.
 ## Arguments
 
 | Argument        |       Description        | Value type |
-| ----------------- |:-----------------------------:|:-------------:|
+|-----------------|:------------------------:|:----------:|
 | ```<package>``` | The package to uninstall | ```str```  |
+
+## Flags
+
+| Argument         |                     Description                      |
+|------------------|:----------------------------------------------------:|
+| ```--dev```      | Specifies whether the command is in development mode |
+| ```--virtual```  |    Specifies whether the command is virtual mode     |
+| ```--simulate``` |      Specifies whether the command is simulated      |

docs/build/html/_sources/cli.update.md.txt

@@ -5,3 +5,9 @@ Updates the CPL and project dependencies.
 cpl **update** <br>
 cpl **u** <br>
 cpl **U**
+
+## Flags
+
+| Argument         |                     Description                      |
+|------------------|:----------------------------------------------------:|
+| ```--simulate``` |      Specifies whether the command is simulated      |

docs/build/html/_sources/cpl_core.pipes.rst.txt

@@ -0,0 +1,77 @@
+cpl\_core.pipes
+=======================
+
+Submodules
+----------
+
+cpl\_core.pipes.bool\_pipe module
+---------------------------------
+
+.. automodule:: cpl_core.pipes.bool_pipe
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+cpl\_core.pipes.first\_char\_to\_lower\_pipe module
+---------------------------------------------------
+
+.. automodule:: cpl_core.pipes.first_char_to_lower_pipe
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+cpl\_core.pipes.first\_to\_upper\_pipe module
+---------------------------------------------
+
+.. automodule:: cpl_core.pipes.first_to_upper_pipe
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+cpl\_core.pipes.ip\_address\_pipe module
+----------------------------------------
+
+.. automodule:: cpl_core.pipes.ip_address_pipe
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+cpl\_core.pipes.pipe\_abc module
+--------------------------------
+
+.. automodule:: cpl_core.pipes.pipe_abc
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+cpl\_core.pipes.to\_camel\_case\_pipe module
+--------------------------------------------
+
+.. automodule:: cpl_core.pipes.to_camel_case_pipe
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+cpl\_core.pipes.to\_snake\_case\_pipe module
+--------------------------------------------
+
+.. automodule:: cpl_core.pipes.to_snake_case_pipe
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+cpl\_core.pipes.version\_pipe module
+------------------------------------
+
+.. automodule:: cpl_core.pipes.version_pipe
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: cpl_core.pipes
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/build/html/_sources/cpl_core.rst.txt

@@ -12,5 +12,6 @@ API Reference
     cpl_core.environment
     cpl_core.logging
     cpl_core.mailing
+    cpl_core.pipes
     cpl_core.time
     cpl_core.utils

docs/build/html/_sources/cpl_query.tests.rst.txt

@@ -1,45 +0,0 @@
-cpl\_query.tests package
-========================
-
-Submodules
-----------
-
-cpl\_query.tests.iterable\_test module
---------------------------------------
-
-.. automodule:: cpl_query.tests.iterable_test
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-cpl\_query.tests.models module
-------------------------------
-
-.. automodule:: cpl_query.tests.models
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-cpl\_query.tests.query\_test module
------------------------------------
-
-.. automodule:: cpl_query.tests.query_test
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-cpl\_query.tests.tester module
-------------------------------
-
-.. automodule:: cpl_query.tests.tester
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: cpl_query.tests
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/build/html/_sources/getting_started.rst.txt

@@ -6,4 +6,5 @@ Getting started
 
     quickstart
     setup
+    tutorials
 

docs/build/html/_sources/introduction.md.txt

@@ -4,6 +4,53 @@ The Common Python Library (CPL) is a package for python and a development platfo
 
 This CPL docs help you learn, understand and use the package. From your first application to complex apps for enterprises.
 
+## Feature overview
+
+- Expandle
+- Application base
+  - Standardized application classes
+  - Application object builder
+  - Application extension classes
+  - Startup classes
+  - Startup extension classes
+- Configuration
+  - Configure via object mapped JSON
+  - Console argument handling
+- Console class for in and output
+  - Banner
+  - Spinner
+  - Options (menu)
+  - Table
+  - Write
+  - Write_at
+  - Write_line
+  - Write_line_at
+- Dependency injection
+  - Service lifetimes: singleton, scoped and transient
+- Providing of application environment
+  - Environment (development, staging, testing, production)
+  - Appname
+  - Customer
+  - Hostname
+  - Runtime directory
+  - Working directory
+- Logging
+  - Standardized logger
+  - Log-level (FATAL, ERROR, WARN, INFO, DEBUG & TRACE)
+- Mail handling
+  - Send mails
+- Pipe classes
+  - Convert input
+- Utils
+  - Credential manager
+    - Encryption via BASE64
+  - PIP wrapper class based on subprocess
+    - Run pip commands
+  - String converter to different variants
+    - to_lower_case
+    - to_camel_case
+    - ...
+
 ## Explore
 
 - [Getting started](quickstart)

docs/build/html/_sources/tutorials.appsettings.md.txt

@@ -0,0 +1 @@
+# Using appsettings.json

docs/build/html/_sources/tutorials.console-arguments.md.txt

@@ -0,0 +1 @@
+# Handle console arguments

docs/build/html/_sources/tutorials.console.md.txt

@@ -0,0 +1 @@
+# Use cpl_core.console.Console

docs/build/html/_sources/tutorials.create-startup.md.txt

@@ -0,0 +1 @@
+# Create startup class

docs/build/html/_sources/tutorials.extend-application.md.txt

@@ -0,0 +1 @@
+# Extend application

docs/build/html/_sources/tutorials.extend-startup.md.txt

@@ -0,0 +1 @@
+# Extend startup

docs/build/html/_sources/tutorials.logging.md.txt

@@ -0,0 +1 @@
+# Use builtin logger

docs/build/html/_sources/tutorials.mail.md.txt

@@ -0,0 +1 @@
+# Send mails

docs/build/html/_sources/tutorials.rst.txt

@@ -0,0 +1,14 @@
+Tutorials
+=============
+
+.. toctree::
+    :maxdepth: 4
+
+    tutorials.extend-application
+    tutorials.create-startup
+    tutorials.extend-startup
+    tutorials.appsettings
+    tutorials.console-arguments
+    tutorials.console
+    tutorials.logging
+    tutorials.mail

docs/build/html/_static/_sphinx_javascript_frameworks_compat.js

@@ -0,0 +1,134 @@
+/*
+ * _sphinx_javascript_frameworks_compat.js
+ * ~~~~~~~~~~
+ *
+ * Compatability shim for jQuery and underscores.js.
+ *
+ * WILL BE REMOVED IN Sphinx 6.0
+ * xref RemovedInSphinx60Warning
+ *
+ */
+
+/**
+ * select a different prefix for underscore
+ */
+$u = _.noConflict();
+
+
+/**
+ * small helper function to urldecode strings
+ *
+ * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL
+ */
+jQuery.urldecode = function(x) {
+    if (!x) {
+        return x
+    }
+    return decodeURIComponent(x.replace(/\+/g, ' '));
+};
+
+/**
+ * small helper function to urlencode strings
+ */
+jQuery.urlencode = encodeURIComponent;
+
+/**
+ * This function returns the parsed url parameters of the
+ * current request. Multiple values per key are supported,
+ * it will always return arrays of strings for the value parts.
+ */
+jQuery.getQueryParameters = function(s) {
+    if (typeof s === 'undefined')
+        s = document.location.search;
+    var parts = s.substr(s.indexOf('?') + 1).split('&');
+    var result = {};
+    for (var i = 0; i < parts.length; i++) {
+        var tmp = parts[i].split('=', 2);
+        var key = jQuery.urldecode(tmp[0]);
+        var value = jQuery.urldecode(tmp[1]);
+        if (key in result)
+            result[key].push(value);
+        else
+            result[key] = [value];
+    }
+    return result;
+};
+
+/**
+ * highlight a given string on a jquery object by wrapping it in
+ * span elements with the given class name.
+ */
+jQuery.fn.highlightText = function(text, className) {
+    function highlight(node, addItems) {
+        if (node.nodeType === 3) {
+            var val = node.nodeValue;
+            var pos = val.toLowerCase().indexOf(text);
+            if (pos >= 0 &&
+                !jQuery(node.parentNode).hasClass(className) &&
+                !jQuery(node.parentNode).hasClass("nohighlight")) {
+                var span;
+                var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg");
+                if (isInSVG) {
+                    span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
+                } else {
+                    span = document.createElement("span");
+                    span.className = className;
+                }
+                span.appendChild(document.createTextNode(val.substr(pos, text.length)));
+                node.parentNode.insertBefore(span, node.parentNode.insertBefore(
+                    document.createTextNode(val.substr(pos + text.length)),
+                    node.nextSibling));
+                node.nodeValue = val.substr(0, pos);
+                if (isInSVG) {
+                    var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
+                    var bbox = node.parentElement.getBBox();
+                    rect.x.baseVal.value = bbox.x;
+                    rect.y.baseVal.value = bbox.y;
+                    rect.width.baseVal.value = bbox.width;
+                    rect.height.baseVal.value = bbox.height;
+                    rect.setAttribute('class', className);
+                    addItems.push({
+                        "parent": node.parentNode,
+                        "target": rect});
+                }
+            }
+        }
+        else if (!jQuery(node).is("button, select, textarea")) {
+            jQuery.each(node.childNodes, function() {
+                highlight(this, addItems);
+            });
+        }
+    }
+    var addItems = [];
+    var result = this.each(function() {
+        highlight(this, addItems);
+    });
+    for (var i = 0; i < addItems.length; ++i) {
+        jQuery(addItems[i].parent).before(addItems[i].target);
+    }
+    return result;
+};
+
+/*
+ * backward compatibility for jQuery.browser
+ * This will be supported until firefox bug is fixed.
+ */
+if (!jQuery.browser) {
+    jQuery.uaMatch = function(ua) {
+        ua = ua.toLowerCase();
+
+        var match = /(chrome)[ \/]([\w.]+)/.exec(ua) ||
+            /(webkit)[ \/]([\w.]+)/.exec(ua) ||
+            /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) ||
+            /(msie) ([\w.]+)/.exec(ua) ||
+            ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) ||
+            [];
+
+        return {
+            browser: match[ 1 ] || "",
+            version: match[ 2 ] || "0"
+        };
+    };
+    jQuery.browser = {};
+    jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true;
+}

docs/build/html/_static/basic.css

@@ -4,7 +4,7 @@
  *
  * Sphinx stylesheet -- basic theme.
  *
- * :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
+ * :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
  * :license: BSD, see LICENSE for details.
  *
  */
@@ -130,7 +130,7 @@ ul.search li a {
     font-weight: bold;
 }
 
-ul.search li div.context {
+ul.search li p.context {
     color: #888;
     margin: 2px 0 0 30px;
     text-align: left;
@@ -222,7 +222,7 @@ table.modindextable td {
 /* -- general body styles --------------------------------------------------- */
 
 div.body {
-    min-width: 450px;
+    min-width: 360px;
     max-width: 800px;
 }
 
@@ -236,7 +236,6 @@ div.body p, div.body dd, div.body li, div.body blockquote {
 a.headerlink {
     visibility: hidden;
 }
-
 a.brackets:before,
 span.brackets > a:before{
     content: "[";
@@ -247,6 +246,7 @@ span.brackets > a:after {
     content: "]";
 }
 
+
 h1:hover > a.headerlink,
 h2:hover > a.headerlink,
 h3:hover > a.headerlink,
@@ -277,25 +277,25 @@ p.rubric {
     font-weight: bold;
 }
 
-img.align-left, .figure.align-left, object.align-left {
+img.align-left, figure.align-left, .figure.align-left, object.align-left {
     clear: left;
     float: left;
     margin-right: 1em;
 }
 
-img.align-right, .figure.align-right, object.align-right {
+img.align-right, figure.align-right, .figure.align-right, object.align-right {
     clear: right;
     float: right;
     margin-left: 1em;
 }
 
-img.align-center, .figure.align-center, object.align-center {
+img.align-center, figure.align-center, .figure.align-center, object.align-center {
   display: block;
   margin-left: auto;
   margin-right: auto;
 }
 
-img.align-default, .figure.align-default {
+img.align-default, figure.align-default, .figure.align-default {
   display: block;
   margin-left: auto;
   margin-right: auto;
@@ -319,7 +319,8 @@ img.align-default, .figure.align-default {
 
 /* -- sidebars -------------------------------------------------------------- */
 
-div.sidebar {
+div.sidebar,
+aside.sidebar {
     margin: 0 0 0.5em 1em;
     border: 1px solid #ddb;
     padding: 7px;
@@ -333,13 +334,11 @@ div.sidebar {
 p.sidebar-title {
     font-weight: bold;
 }
-
 div.admonition, div.topic, blockquote {
     clear: left;
 }
 
 /* -- topics ---------------------------------------------------------------- */
-
 div.topic {
     border: 1px solid #ccc;
     padding: 7px;
@@ -377,12 +376,14 @@ div.body p.centered {
 /* -- content of sidebars/topics/admonitions -------------------------------- */
 
 div.sidebar > :last-child,
+aside.sidebar > :last-child,
 div.topic > :last-child,
 div.admonition > :last-child {
     margin-bottom: 0;
 }
 
 div.sidebar::after,
+aside.sidebar::after,
 div.topic::after,
 div.admonition::after,
 blockquote::after {
@@ -425,10 +426,6 @@ table.docutils td, table.docutils th {
     border-bottom: 1px solid #aaa;
 }
 
-table.footnote td, table.footnote th {
-    border: 0 !important;
-}
-
 th {
     text-align: left;
     padding-right: 5px;
@@ -455,20 +452,22 @@ td > :last-child {
 
 /* -- figures --------------------------------------------------------------- */
 
-div.figure {
+div.figure, figure {
     margin: 0.5em;
     padding: 0.5em;
 }
 
-div.figure p.caption {
+div.figure p.caption, figcaption {
     padding: 0.3em;
 }
 
-div.figure p.caption span.caption-number {
+div.figure p.caption span.caption-number,
+figcaption span.caption-number {
     font-style: italic;
 }
 
-div.figure p.caption span.caption-text {
+div.figure p.caption span.caption-text,
+figcaption span.caption-text {
 }
 
 /* -- field list styles ----------------------------------------------------- */
@@ -503,6 +502,63 @@ table.hlist td {
     vertical-align: top;
 }
 
+/* -- object description styles --------------------------------------------- */
+
+.sig {
+	font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
+}
+
+.sig-name, code.descname {
+    background-color: transparent;
+    font-weight: bold;
+}
+
+.sig-name {
+	font-size: 1.1em;
+}
+
+code.descname {
+    font-size: 1.2em;
+}
+
+.sig-prename, code.descclassname {
+    background-color: transparent;
+}
+
+.optional {
+    font-size: 1.3em;
+}
+
+.sig-paren {
+    font-size: larger;
+}
+
+.sig-param.n {
+	font-style: italic;
+}
+
+/* C++ specific styling */
+
+.sig-inline.c-texpr,
+.sig-inline.cpp-texpr {
+	font-family: unset;
+}
+
+.sig.c   .k, .sig.c   .kt,
+.sig.cpp .k, .sig.cpp .kt {
+	color: #0033B3;
+}
+
+.sig.c   .m,
+.sig.cpp .m {
+	color: #1750EB;
+}
+
+.sig.c   .s, .sig.c   .sc,
+.sig.cpp .s, .sig.cpp .sc {
+	color: #067D17;
+}
+
 
 /* -- other body styles ----------------------------------------------------- */
 
@@ -553,6 +609,7 @@ ul.simple p {
     margin-bottom: 0;
 }
 
+/* Docutils 0.17 and older (footnotes & citations) */
 dl.footnote > dt,
 dl.citation > dt {
     float: left;
@@ -570,6 +627,33 @@ dl.citation > dd:after {
     clear: both;
 }
 
+/* Docutils 0.18+ (footnotes & citations) */
+aside.footnote > span,
+div.citation > span {
+    float: left;
+}
+aside.footnote > span:last-of-type,
+div.citation > span:last-of-type {
+  padding-right: 0.5em;
+}
+aside.footnote > p {
+  margin-left: 2em;
+}
+div.citation > p {
+  margin-left: 4em;
+}
+aside.footnote > p:last-of-type,
+div.citation > p:last-of-type {
+    margin-bottom: 0em;
+}
+aside.footnote > p:last-of-type:after,
+div.citation > p:last-of-type:after {
+    content: "";
+    clear: both;
+}
+
+/* Footnotes & citations ends */
+
 dl.field-list {
     display: grid;
     grid-template-columns: fit-content(30%) auto;
@@ -629,14 +713,6 @@ dl.glossary dt {
     font-size: 1.1em;
 }
 
-.optional {
-    font-size: 1.3em;
-}
-
-.sig-paren {
-    font-size: larger;
-}
-
 .versionmodified {
     font-style: italic;
 }
@@ -677,8 +753,9 @@ dl.glossary dt {
 
 .classifier:before {
     font-style: normal;
-    margin: 0.5em;
+    margin: 0 0.5em;
     content: ":";
+    display: inline-block;
 }
 
 abbr, acronym {
@@ -702,6 +779,7 @@ span.pre {
     -ms-hyphens: none;
     -webkit-hyphens: none;
     hyphens: none;
+    white-space: nowrap;
 }
 
 div[class*="highlight-"] {
@@ -765,8 +843,12 @@ div.code-block-caption code {
 
 table.highlighttable td.linenos,
 span.linenos,
-div.doctest > div.highlight span.gp {  /* gp: Generic.Prompt */
+div.highlight span.gp {  /* gp: Generic.Prompt */
   user-select: none;
+  -webkit-user-select: text; /* Safari fallback only */
+  -webkit-user-select: none; /* Chrome/Safari */
+  -moz-user-select: none; /* Firefox */
+  -ms-user-select: none; /* IE10+ */
 }
 
 div.code-block-caption span.caption-number {
@@ -781,16 +863,6 @@ div.literal-block-wrapper {
     margin: 1em 0;
 }
 
-code.descname {
-    background-color: transparent;
-    font-weight: bold;
-    font-size: 1.2em;
-}
-
-code.descclassname {
-    background-color: transparent;
-}
-
 code.xref, a code {
     background-color: transparent;
     font-weight: bold;

docs/build/html/_static/doctools.js

@@ -2,320 +2,263 @@
  * doctools.js
  * ~~~~~~~~~~~
  *
- * Sphinx JavaScript utilities for all documentation.
+ * Base JavaScript utilities for all Sphinx HTML documentation.
  *
- * :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
+ * :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
  * :license: BSD, see LICENSE for details.
  *
  */
+"use strict";
 
-/**
- * select a different prefix for underscore
- */
-$u = _.noConflict();
-
-/**
- * make the code below compatible with browsers without
- * an installed firebug like debugger
-if (!window.console || !console.firebug) {
-  var names = ["log", "debug", "info", "warn", "error", "assert", "dir",
-    "dirxml", "group", "groupEnd", "time", "timeEnd", "count", "trace",
-    "profile", "profileEnd"];
-  window.console = {};
-  for (var i = 0; i < names.length; ++i)
-    window.console[names[i]] = function() {};
+const _ready = (callback) => {
+  if (document.readyState !== "loading") {
+    callback();
+  } else {
+    document.addEventListener("DOMContentLoaded", callback);
   }
- */
-
-/**
- * small helper function to urldecode strings
- *
- * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL
- */
-jQuery.urldecode = function(x) {
-  if (!x) {
-    return x
-  }
-  return decodeURIComponent(x.replace(/\+/g, ' '));
 };
 
 /**
- * small helper function to urlencode strings
- */
-jQuery.urlencode = encodeURIComponent;
-
-/**
- * This function returns the parsed url parameters of the
- * current request. Multiple values per key are supported,
- * it will always return arrays of strings for the value parts.
- */
-jQuery.getQueryParameters = function(s) {
-  if (typeof s === 'undefined')
-    s = document.location.search;
-  var parts = s.substr(s.indexOf('?') + 1).split('&');
-  var result = {};
-  for (var i = 0; i < parts.length; i++) {
-    var tmp = parts[i].split('=', 2);
-    var key = jQuery.urldecode(tmp[0]);
-    var value = jQuery.urldecode(tmp[1]);
-    if (key in result)
-      result[key].push(value);
-    else
-      result[key] = [value];
-  }
-  return result;
-};
-
-/**
- * highlight a given string on a jquery object by wrapping it in
+ * highlight a given string on a node by wrapping it in
  * span elements with the given class name.
  */
-jQuery.fn.highlightText = function(text, className) {
-  function highlight(node, addItems) {
-    if (node.nodeType === 3) {
-      var val = node.nodeValue;
-      var pos = val.toLowerCase().indexOf(text);
-      if (pos >= 0 &&
-          !jQuery(node.parentNode).hasClass(className) &&
-          !jQuery(node.parentNode).hasClass("nohighlight")) {
-        var span;
-        var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg");
+const _highlight = (node, addItems, text, className) => {
+  if (node.nodeType === Node.TEXT_NODE) {
+    const val = node.nodeValue;
+    const parent = node.parentNode;
+    const pos = val.toLowerCase().indexOf(text);
+    if (
+      pos >= 0 &&
+      !parent.classList.contains(className) &&
+      !parent.classList.contains("nohighlight")
+    ) {
+      let span;
+
+      const closestNode = parent.closest("body, svg, foreignObject");
+      const isInSVG = closestNode && closestNode.matches("svg");
       if (isInSVG) {
         span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
       } else {
         span = document.createElement("span");
-          span.className = className;
+        span.classList.add(className);
       }
+
       span.appendChild(document.createTextNode(val.substr(pos, text.length)));
-        node.parentNode.insertBefore(span, node.parentNode.insertBefore(
+      parent.insertBefore(
+        span,
+        parent.insertBefore(
           document.createTextNode(val.substr(pos + text.length)),
-          node.nextSibling));
+          node.nextSibling
+        )
+      );
       node.nodeValue = val.substr(0, pos);
+
       if (isInSVG) {
-          var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
-          var bbox = node.parentElement.getBBox();
+        const rect = document.createElementNS(
+          "http://www.w3.org/2000/svg",
+          "rect"
+        );
+        const bbox = parent.getBBox();
         rect.x.baseVal.value = bbox.x;
         rect.y.baseVal.value = bbox.y;
         rect.width.baseVal.value = bbox.width;
         rect.height.baseVal.value = bbox.height;
-          rect.setAttribute('class', className);
-          addItems.push({
-              "parent": node.parentNode,
-              "target": rect});
+        rect.setAttribute("class", className);
+        addItems.push({ parent: parent, target: rect });
       }
     }
+  } else if (node.matches && !node.matches("button, select, textarea")) {
+    node.childNodes.forEach((el) => _highlight(el, addItems, text, className));
   }
-    else if (!jQuery(node).is("button, select, textarea")) {
-      jQuery.each(node.childNodes, function() {
-        highlight(this, addItems);
-      });
-    }
-  }
-  var addItems = [];
-  var result = this.each(function() {
-    highlight(this, addItems);
-  });
-  for (var i = 0; i < addItems.length; ++i) {
-    jQuery(addItems[i].parent).before(addItems[i].target);
-  }
-  return result;
 };
-
-/*
- * backward compatibility for jQuery.browser
- * This will be supported until firefox bug is fixed.
- */
-if (!jQuery.browser) {
-  jQuery.uaMatch = function(ua) {
-    ua = ua.toLowerCase();
-
-    var match = /(chrome)[ \/]([\w.]+)/.exec(ua) ||
-      /(webkit)[ \/]([\w.]+)/.exec(ua) ||
-      /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) ||
-      /(msie) ([\w.]+)/.exec(ua) ||
-      ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) ||
-      [];
-
-    return {
-      browser: match[ 1 ] || "",
-      version: match[ 2 ] || "0"
+const _highlightText = (thisNode, text, className) => {
+  let addItems = [];
+  _highlight(thisNode, addItems, text, className);
+  addItems.forEach((obj) =>
+    obj.parent.insertAdjacentElement("beforebegin", obj.target)
+  );
 };
-  };
-  jQuery.browser = {};
-  jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true;
-}
 
 /**
  * Small JavaScript module for the documentation.
  */
-var Documentation = {
-
-  init : function() {
-    this.fixFirefoxAnchorBug();
-    this.highlightSearchWords();
-    this.initIndexTable();
-    if (DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) {
-      this.initOnKeyListeners();
-    }
+const Documentation = {
+  init: () => {
+    Documentation.highlightSearchWords();
+    Documentation.initDomainIndexTable();
+    Documentation.initOnKeyListeners();
   },
 
   /**
    * i18n support
    */
   TRANSLATIONS: {},
-  PLURAL_EXPR : function(n) { return n === 1 ? 0 : 1; },
-  LOCALE : 'unknown',
+  PLURAL_EXPR: (n) => (n === 1 ? 0 : 1),
+  LOCALE: "unknown",
 
   // gettext and ngettext don't access this so that the functions
   // can safely bound to a different name (_ = Documentation.gettext)
-  gettext : function(string) {
-    var translated = Documentation.TRANSLATIONS[string];
-    if (typeof translated === 'undefined')
-      return string;
-    return (typeof translated === 'string') ? translated : translated[0];
+  gettext: (string) => {
+    const translated = Documentation.TRANSLATIONS[string];
+    switch (typeof translated) {
+      case "undefined":
+        return string; // no translation
+      case "string":
+        return translated; // translation exists
+      default:
+        return translated[0]; // (singular, plural) translation tuple exists
+    }
   },
 
-  ngettext : function(singular, plural, n) {
-    var translated = Documentation.TRANSLATIONS[singular];
-    if (typeof translated === 'undefined')
-      return (n == 1) ? singular : plural;
-    return translated[Documentation.PLURALEXPR(n)];
+  ngettext: (singular, plural, n) => {
+    const translated = Documentation.TRANSLATIONS[singular];
+    if (typeof translated !== "undefined")
+      return translated[Documentation.PLURAL_EXPR(n)];
+    return n === 1 ? singular : plural;
   },
 
-  addTranslations : function(catalog) {
-    for (var key in catalog.messages)
-      this.TRANSLATIONS[key] = catalog.messages[key];
-    this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')');
-    this.LOCALE = catalog.locale;
-  },
-
-  /**
-   * add context elements like header anchor links
-   */
-  addContextElements : function() {
-    $('div[id] > :header:first').each(function() {
-      $('<a class="headerlink">\u00B6</a>').
-      attr('href', '#' + this.id).
-      attr('title', _('Permalink to this headline')).
-      appendTo(this);
-    });
-    $('dt[id]').each(function() {
-      $('<a class="headerlink">\u00B6</a>').
-      attr('href', '#' + this.id).
-      attr('title', _('Permalink to this definition')).
-      appendTo(this);
-    });
-  },
-
-  /**
-   * workaround a firefox stupidity
-   * see: https://bugzilla.mozilla.org/show_bug.cgi?id=645075
-   */
-  fixFirefoxAnchorBug : function() {
-    if (document.location.hash && $.browser.mozilla)
-      window.setTimeout(function() {
-        document.location.href += '';
-      }, 10);
+  addTranslations: (catalog) => {
+    Object.assign(Documentation.TRANSLATIONS, catalog.messages);
+    Documentation.PLURAL_EXPR = new Function(
+      "n",
+      `return (${catalog.plural_expr})`
+    );
+    Documentation.LOCALE = catalog.locale;
   },
 
   /**
    * highlight the search words provided in the url in the text
    */
-  highlightSearchWords : function() {
-    var params = $.getQueryParameters();
-    var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : [];
-    if (terms.length) {
-      var body = $('div.body');
-      if (!body.length) {
-        body = $('body');
-      }
-      window.setTimeout(function() {
-        $.each(terms, function() {
-          body.highlightText(this.toLowerCase(), 'highlighted');
-        });
-      }, 10);
-      $('<p class="highlight-link"><a href="javascript:Documentation.' +
-        'hideSearchWords()">' + _('Hide Search Matches') + '</a></p>')
-          .appendTo($('#searchbox'));
-    }
-  },
+  highlightSearchWords: () => {
+    const highlight =
+      new URLSearchParams(window.location.search).get("highlight") || "";
+    const terms = highlight.toLowerCase().split(/\s+/).filter(x => x);
+    if (terms.length === 0) return; // nothing to do
 
-  /**
-   * init the domain index toggle buttons
-   */
-  initIndexTable : function() {
-    var togglers = $('img.toggler').click(function() {
-      var src = $(this).attr('src');
-      var idnum = $(this).attr('id').substr(7);
-      $('tr.cg-' + idnum).toggle();
-      if (src.substr(-9) === 'minus.png')
-        $(this).attr('src', src.substr(0, src.length-9) + 'plus.png');
-      else
-        $(this).attr('src', src.substr(0, src.length-8) + 'minus.png');
-    }).css('display', '');
-    if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) {
-        togglers.click();
-    }
+    // There should never be more than one element matching "div.body"
+    const divBody = document.querySelectorAll("div.body");
+    const body = divBody.length ? divBody[0] : document.querySelector("body");
+    window.setTimeout(() => {
+      terms.forEach((term) => _highlightText(body, term, "highlighted"));
+    }, 10);
+
+    const searchBox = document.getElementById("searchbox");
+    if (searchBox === null) return;
+    searchBox.appendChild(
+      document
+        .createRange()
+        .createContextualFragment(
+          '<p class="highlight-link">' +
+            '<a href="javascript:Documentation.hideSearchWords()">' +
+            Documentation.gettext("Hide Search Matches") +
+            "</a></p>"
+        )
+    );
   },
 
   /**
    * helper function to hide the search marks again
    */
-  hideSearchWords : function() {
-    $('#searchbox .highlight-link').fadeOut(300);
-    $('span.highlighted').removeClass('highlighted');
+  hideSearchWords: () => {
+    document
+      .querySelectorAll("#searchbox .highlight-link")
+      .forEach((el) => el.remove());
+    document
+      .querySelectorAll("span.highlighted")
+      .forEach((el) => el.classList.remove("highlighted"));
+    const url = new URL(window.location);
+    url.searchParams.delete("highlight");
+    window.history.replaceState({}, "", url);
   },
 
   /**
-   * make the url absolute
+   * helper function to focus on search bar
    */
-  makeURL : function(relativeURL) {
-    return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL;
+  focusSearchBar: () => {
+    document.querySelectorAll("input[name=q]")[0]?.focus();
   },
 
   /**
-   * get the current relative url
+   * Initialise the domain index toggle buttons
    */
-  getCurrentURL : function() {
-    var path = document.location.pathname;
-    var parts = path.split(/\//);
-    $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() {
-      if (this === '..')
-        parts.pop();
-    });
-    var url = parts.join('/');
-    return path.substring(url.lastIndexOf('/') + 1, path.length - 1);
-  },
-
-  initOnKeyListeners: function() {
-    $(document).keydown(function(event) {
-      var activeElementType = document.activeElement.tagName;
-      // don't navigate when in search box, textarea, dropdown or button
-      if (activeElementType !== 'TEXTAREA' && activeElementType !== 'INPUT' && activeElementType !== 'SELECT'
-          && activeElementType !== 'BUTTON' && !event.altKey && !event.ctrlKey && !event.metaKey
-          && !event.shiftKey) {
-        switch (event.keyCode) {
-          case 37: // left
-            var prevHref = $('link[rel="prev"]').prop('href');
-            if (prevHref) {
-              window.location.href = prevHref;
-              return false;
-            }
-          case 39: // right
-            var nextHref = $('link[rel="next"]').prop('href');
-            if (nextHref) {
-              window.location.href = nextHref;
-              return false;
-            }
-        }
-      }
-    });
+  initDomainIndexTable: () => {
+    const toggler = (el) => {
+      const idNumber = el.id.substr(7);
+      const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`);
+      if (el.src.substr(-9) === "minus.png") {
+        el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`;
+        toggledRows.forEach((el) => (el.style.display = "none"));
+      } else {
+        el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`;
+        toggledRows.forEach((el) => (el.style.display = ""));
       }
     };
 
-// quick alias for translations
-_ = Documentation.gettext;
+    const togglerElements = document.querySelectorAll("img.toggler");
+    togglerElements.forEach((el) =>
+      el.addEventListener("click", (event) => toggler(event.currentTarget))
+    );
+    togglerElements.forEach((el) => (el.style.display = ""));
+    if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler);
+  },
 
-$(document).ready(function() {
-  Documentation.init();
+  initOnKeyListeners: () => {
+    // only install a listener if it is really needed
+    if (
+      !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS &&
+      !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS
+    )
+      return;
+
+    const blacklistedElements = new Set([
+      "TEXTAREA",
+      "INPUT",
+      "SELECT",
+      "BUTTON",
+    ]);
+    document.addEventListener("keydown", (event) => {
+      if (blacklistedElements.has(document.activeElement.tagName)) return; // bail for input elements
+      if (event.altKey || event.ctrlKey || event.metaKey) return; // bail with special keys
+
+      if (!event.shiftKey) {
+        switch (event.key) {
+          case "ArrowLeft":
+            if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break;
+
+            const prevLink = document.querySelector('link[rel="prev"]');
+            if (prevLink && prevLink.href) {
+              window.location.href = prevLink.href;
+              event.preventDefault();
+            }
+            break;
+          case "ArrowRight":
+            if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break;
+
+            const nextLink = document.querySelector('link[rel="next"]');
+            if (nextLink && nextLink.href) {
+              window.location.href = nextLink.href;
+              event.preventDefault();
+            }
+            break;
+          case "Escape":
+            if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break;
+            Documentation.hideSearchWords();
+            event.preventDefault();
+        }
+      }
+
+      // some keyboard layouts may need Shift to get /
+      switch (event.key) {
+        case "/":
+          if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break;
+          Documentation.focusSearchBar();
+          event.preventDefault();
+      }
     });
+  },
+};
+
+// quick alias for translations
+const _ = Documentation.gettext;
+
+_ready(Documentation.init);

docs/build/html/_static/documentation_options.js

@@ -1,12 +1,14 @@
 var DOCUMENTATION_OPTIONS = {
     URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
     VERSION: '',
-    LANGUAGE: 'None',
+    LANGUAGE: 'en',
     COLLAPSE_INDEX: false,
     BUILDER: 'html',
     FILE_SUFFIX: '.html',
     LINK_SUFFIX: '.html',
     HAS_SOURCE: true,
     SOURCELINK_SUFFIX: '.txt',
-    NAVIGATION_WITH_KEYS: false
+    NAVIGATION_WITH_KEYS: false,
+    SHOW_SEARCH_SUMMARY: true,
+    ENABLE_SEARCH_SHORTCUTS: false,
 };