Update and improve documentation

doc/api.rst

@@ -0,0 +1,5 @@
+.. _api:
+
+:octicon:`cpu` API Reference
+=============================
+

doc/changes/unreleased.md

@@ -13,6 +13,10 @@
 
 * #33: Updated to Python 3.10
 
+## Documentation
+
+* Update project documentation
+
 ## Internal
 * Relock Dependencies
 

doc/dependencies.rst

@@ -0,0 +1,27 @@
+.. _dependencies:
+
+:octicon:`package` Dependencies
+===============================
+
+Run Time Dependencies
+---------------------
+
+================================= ================================= ================
+Dependency                        Purpose                           License
+================================= ================================= ================
+`Python 3`_                       Python version 3.6.1 and above    PSF
+================================= ================================= ================
+
+Test Dependencies
+-----------------
+
+===================== ========================== ========
+Dependency            Purpose                    License
+===================== ========================== ========
+`Pytest`_             Testing framework          MIT
+`Prysk`_              Testing framework          GPL
+===================== ========================== ========
+
+.. _Python 3: https://docs.python.org
+.. _Pytest: https://docs.pytest.org/en/stable/
+.. _Prysk: https://www.prysk.net

doc/design.rst

@@ -0,0 +1,23 @@
+.. _design_document:
+
+:octicon:`repo` Design Document
+===============================
+
+Motivation
+----------
+
+Overview
+---------
+
+Design
+------
+
+Design Principles
++++++++++++++++++
+
+Design Decisions
+++++++++++++++++
+
+Detailed Design
++++++++++++++++
+

doc/developer_guide/developer_guide.rst

@@ -1,2 +1,79 @@
-Developer Guide
-===============
+.. _developer_guide:
+
+:octicon:`tools` Developer Guide
+================================
+
+Creating a Release
+++++++++++++++++++
+
+Prepare the Release
+-------------------
+
+To prepare for a release, a pull request with the following parameters needs to be created:
+
+- Updated version numbers
+- Updated the changelog
+- Updated workflow templates (not automated yet)
+
+This can be achieved by running the following command:
+
+.. code-block:: shell
+
+   nox -s prepare-release -- <major>.<minor>.<patch>
+
+Replace `<major>`, `<minor>`, and `<patch>` with the appropriate version numbers.
+Once the PR is successfully merged, the release can be triggered (see next section).
+
+Triggering the Release
+----------------------
+
+To trigger a release, a new tag must be pushed to GitHub. For further details, see `.github/workflows/ci-cd.yml`.
+
+1. Create a local tag with the appropriate version number:
+
+    .. code-block:: shell
+
+        git tag x.y.z
+
+2. Push the tag to GitHub:
+
+    .. code-block:: shell
+
+        git push origin x.y.z
+
+
+What to do if the release failed?
+---------------------------------
+
+The release failed during pre-release checks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+#. Delete the local tag
+
+    .. code-block:: shell
+
+        git tag -d x.y.z
+
+#. Delete the remote tag
+
+    .. code-block:: shell
+
+        git push --delete origin x.y.z
+
+#. Fix the issue(s) which lead to the failing checks
+#. Start the release process from the beginning
+
+
+One of the release steps failed (Partial Release)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#. Check the Github action/workflow to see which steps failed
+#. Finish or redo the failed release steps manually
+
+.. note:: Example
+
+    **Scenario**: Publishing of the release on Github was successfully but during the PyPi release, the upload step got interrupted.
+
+    **Solution**: Manually push the package to PyPi
+
+
+

doc/index.rst

@@ -1,12 +1,48 @@
-Documentation of the Exasol-Toolbox
------------------------------------
+Error-Reporting-Python
+----------------------
 
 
 .. grid:: 1 1 3 2
     :gutter: 2
     :padding: 0
     :class-container: surface
 
+    .. grid-item-card:: :octicon:`person` User Guide
+        :link: user_guide
+        :link-type: ref
+
+        Resource for users to understand how to utilize this project and its features.
+
+    .. grid-item-card:: :octicon:`tools` Developer Guide
+        :link: developer_guide
+        :link-type: ref
+
+        Instructions and best practices to help developers contribute to the project and set up their development environment.
+
+    .. grid-item-card:: :octicon:`terminal` Tools
+        :link: tools
+        :link-type: ref
+
+        CLI-Tools which are shipped as part of this project.
+
+    .. grid-item-card:: :octicon:`cpu` API Reference
+        :link: api
+        :link-type: ref
+
+        Detailed descriptions, syntax, and usage examples for the API provided by this project.
+
+    .. grid-item-card:: :octicon:`repo` Design Document
+        :link: design_document
+        :link-type: ref
+
+        Document outlining the architectural and design principles and decisions in this project.
+
+    .. grid-item-card:: :octicon:`package` Dependencies
+        :link: dependencies
+        :link-type: ref
+
+        Detailed descriptions of the dependencies
+
     .. grid-item-card:: :octicon:`question` FAQ
         :link: faq
         :link-type: ref
@@ -20,8 +56,11 @@ Documentation of the Exasol-Toolbox
 
    user_guide/user_guide
    developer_guide/developer_guide
-   dependencies
+   tools
+   api
+   design
    faq
+   dependencies
    changes/changelog
 
 

doc/tools.rst

@@ -0,0 +1,30 @@
+.. _tools:
+
+:octicon:`terminal` Tools
+=========================
+
+The python-toolbox ships with a set of command line tools, whose entry point always is the command :code:`tbx`.
+The commands are structured in a *tree* manner, and help is provided along with the command(s) no matter the nesting.
+
+How to get Help
+---------------
+
+.. code-block:: shell
+
+     $ tbx --help
+
+.. code-block:: shell
+
+     $ tbx command --help
+
+.. code-block:: shell
+
+     $ tbx command subcommand --help
+
+.. code-block:: shell
+
+     $ tbx command subcommand subsubcommand --help
+
+
+If the details for a specific command are not sufficient checkout the according subsections bellow,
+or `create an isssue <https://github.com/exasol/python-toolbox/issues/new?assignees=&labels=documentation&projects=&template=documentation.md&title=%F0%9F%93%9A+%3CInsert+Title%3E>`_ if nothing is avialable yet.

doc/user_guide/user_guide.md → doc/user_guide/user_guide.rst

@@ -1,42 +1,53 @@
-# User Guide
+.. _user_guide:
+
+:octicon:`person` User Guide
+============================
 
 This project contains a python library for describing Exasol error messages. 
 This library lets you define errors with a uniform set of attributes. 
-Furthermore, the error message  is implemented to be parseable, 
+Furthermore, the error message is implemented to be parseable, 
 so that you can extract an error catalog from the code.
 
-## Creating an Error Object
+Creating an Error Object
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-Error objects are built using the function `ExaError`. 
-Please keep in mind that error-code should satisfy the error-code format (see [code](#code)).
+Error objects are built using the function ``ExaError``. 
+Please keep in mind that error-code should satisfy the error-code format (see `code`_).
 
 Flexibility is provided by introducing placeholder parameters to the error 
 message.
 
-### code
-This parameter needs to obey the following format (`^[FEW]-[[A-Z][A-Z0-9]+(-[A-Z][A-Z0-9]+)*-[0-9]+$`):
+code
+----
+
+This parameter needs to obey the following format (``^[FEW]-[[A-Z][A-Z0-9]+(-[A-Z][A-Z0-9]+)*-[0-9]+$``):
 
-`severity "-" project-short-tag ["-" module-short-tag] "-" error-number` where,
-- _severity_: either F (Failure, not recoverable), or E (Error, recoverable), 
-or W (warning),
-- _project-short-tag_: alphanumeric starting with alphabet.
-- _module-short-tag_: alphanumeric starting with alphabet.
-- _error-number_: only number.
+``severity "-" project-short-tag ["-" module-short-tag] "-" error-number`` where:
+- *severity*: either F (Failure, not recoverable), or E (Error, recoverable), or W (warning),
+- *project-short-tag*: alphanumeric starting with alphabet.
+- *module-short-tag*: alphanumeric starting with alphabet.
+- *error-number*: only number.
 
-Examples of valide error codes:
+Examples of valid error codes:
 - E-EXA-22004
 - E-EXA-SQL-22004
 - F-VS-QRW-13
 
-### message
+message
+-------
+
 This parameter includes the error description which can be given by either a static
 string or a string containing placeholders in double curly brackets. Parameters 
-of placeholders in the error message can be provided using the `parameters` parameter.
+of placeholders in the error message can be provided using the ``parameters`` parameter.
+
+mitigations
+-----------
 
-### mitigations
 This parameter provides a list of hints on how to fix the error. 
-Parameters of placeholders in the mitigations can be given via the `parameters` parameter.
+Parameters of placeholders in the mitigations can be given via the ``parameters`` parameter.
 
-### parameters
+parameters
+----------
+
 This argument takes a dictionary of placeholder names and the respective parameter values.
 They will be used to replace the placeholders in the mitigations and messages.