diff --git a/doc/api.rst b/doc/api.rst new file mode 100644 index 0000000..246b507 --- /dev/null +++ b/doc/api.rst @@ -0,0 +1,5 @@ +.. _api: + +:octicon:`cpu` API Reference +============================= + diff --git a/doc/changes/unreleased.md b/doc/changes/unreleased.md index d2c0d0f..c894562 100644 --- a/doc/changes/unreleased.md +++ b/doc/changes/unreleased.md @@ -13,6 +13,10 @@ * #33: Updated to Python 3.10 +## Documentation + +* Update project documentation + ## Internal * Relock Dependencies diff --git a/doc/dependencies.md b/doc/dependencies.md deleted file mode 100644 index 6ad24bc..0000000 --- a/doc/dependencies.md +++ /dev/null @@ -1,21 +0,0 @@ -# Dependencies - -## Run Time Dependencies - -| Dependency | Purpose | License | -|-------------------------------|----------------------------------|--------------------| -| [Python 3][python] | Python version 3.6.1 and above | PSF | - - -## Test Dependencies - -| Dependency | Purpose | License | -|------------------|-----------------------------------|---------| -| [Pytest][pytest] | Testing framework | MIT | -| [Prysk][prysk] | Testing framework | GPL | - - - -[python]: https://docs.python.org -[pytest]: https://docs.pytest.org/en/stable/ -[prysk]: https://www.prysk.net diff --git a/doc/dependencies.rst b/doc/dependencies.rst new file mode 100644 index 0000000..4433f1f --- /dev/null +++ b/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 diff --git a/doc/design.rst b/doc/design.rst new file mode 100644 index 0000000..0d954b7 --- /dev/null +++ b/doc/design.rst @@ -0,0 +1,23 @@ +.. _design_document: + +:octicon:`repo` Design Document +=============================== + +Motivation +---------- + +Overview +--------- + +Design +------ + +Design Principles ++++++++++++++++++ + +Design Decisions +++++++++++++++++ + +Detailed Design ++++++++++++++++ + diff --git a/doc/developer_guide/developer_guide.rst b/doc/developer_guide/developer_guide.rst index cf18c40..e250578 100644 --- a/doc/developer_guide/developer_guide.rst +++ b/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 -- .. + +Replace ``, ``, and `` 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 + + + diff --git a/doc/index.rst b/doc/index.rst index acd4e02..32064eb 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,5 +1,5 @@ -Documentation of the Exasol-Toolbox ------------------------------------ +Error-Reporting-Python +---------------------- .. grid:: 1 1 3 2 @@ -7,6 +7,42 @@ Documentation of the Exasol-Toolbox :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 diff --git a/doc/tools.rst b/doc/tools.rst new file mode 100644 index 0000000..0ffb622 --- /dev/null +++ b/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 `_ if nothing is avialable yet. diff --git a/doc/user_guide/user_guide.md b/doc/user_guide/user_guide.rst similarity index 52% rename from doc/user_guide/user_guide.md rename to doc/user_guide/user_guide.rst index a1f4272..16f2ecd 100644 --- a/doc/user_guide/user_guide.md +++ b/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.