From 80b28293f2728825bbe6bda685c0fabd21dc093b Mon Sep 17 00:00:00 2001 From: Nicola Coretti Date: Thu, 6 Jun 2024 15:05:03 +0200 Subject: [PATCH 01/10] Add exasol-toolbox as dependency --- pyproject.toml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 5dff809..916b308 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -28,11 +28,12 @@ python = "^3.8" [tool.poetry.group.dev.dependencies] pytest = "^7.1.2" -prysk = {extras = ["pytest-plugin"], version = "^0.15.1"} +prysk = {extras = ["pytest-plugin"], version = ">=0.15.1"} +exasol-toolbox = ">=0.12.0" [build-system] requires = ["poetry-core>=1.0.0"] build-backend = "poetry.core.masonry.api" [tool.poetry.scripts] -ec = 'exasol.error._cli:main' \ No newline at end of file +ec = 'exasol.error._cli:main' From fdf0d3e02752a528908db55fd473aa82a286ad0d Mon Sep 17 00:00:00 2001 From: Nicola Coretti Date: Thu, 6 Jun 2024 15:08:42 +0200 Subject: [PATCH 02/10] Add documentation build folder to .gitignore --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 284db3d..e14144b 100644 --- a/.gitignore +++ b/.gitignore @@ -136,3 +136,4 @@ poetry.lock # Sphinx doc/_build +.html-documentation From c34af594fc2c6f521985c7ee94535c1d49a50c6b Mon Sep 17 00:00:00 2001 From: Nicola Coretti Date: Thu, 6 Jun 2024 15:11:30 +0200 Subject: [PATCH 03/10] Add noxfile --- noxfile.py | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 noxfile.py diff --git a/noxfile.py b/noxfile.py new file mode 100644 index 0000000..41d2ca8 --- /dev/null +++ b/noxfile.py @@ -0,0 +1,8 @@ +"""defines nox tasks/targets for this project""" +import nox + +# imports all nox task provided by the toolbox +from exasol.toolbox.nox.tasks import * # pylint: disable=wildcard-import disable=unused-wildcard-import + +# default actions to be run if nothing is explicitly specified with the -s option +nox.options.sessions = ["fix"] From 6243cc42d560f12bc537b996cbad46e1477fc5df Mon Sep 17 00:00:00 2001 From: Nicola Coretti Date: Thu, 6 Jun 2024 15:11:38 +0200 Subject: [PATCH 04/10] Add noxconfig --- noxconfig.py | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 noxconfig.py diff --git a/noxconfig.py b/noxconfig.py new file mode 100644 index 0000000..79cdb7e --- /dev/null +++ b/noxconfig.py @@ -0,0 +1,20 @@ +"""Configuration for nox based task runner""" +from __future__ import annotations + +from dataclasses import dataclass +from pathlib import Path +from typing import Iterable + + +@dataclass(frozen=True) +class Config: + """Project specific configuration used by nox infrastructure""" + + root: Path = Path(__file__).parent + doc: Path = Path(__file__).parent / "doc" + version_file: Path = Path(__file__).parent / "exasol" / "error" / "version.py" + path_filters: Iterable[str] = ("dist", ".eggs", "venv") + plugins = [] + + +PROJECT_CONFIG = Config() From 45a6a2015353fcdf9a7f3116e15fec7edd1ef7de Mon Sep 17 00:00:00 2001 From: Nicola Coretti Date: Thu, 6 Jun 2024 16:05:43 +0200 Subject: [PATCH 05/10] Add documentation support --- doc/_static/dark-exasol-logo.svg | 1 + doc/_static/light-exasol-logo.svg | 7 +++ doc/_templates/partials/webfonts.html | 0 doc/_templates/version.html | 12 ++++ doc/changes/changelog.md | 12 ++++ doc/conf.py | 78 +++++++++++++++++++++++++ doc/developer_guide/developer_guide.rst | 2 + doc/faq.rst | 4 ++ doc/index.rst | 27 +++++++++ doc/user_guide/user_guide.md | 8 +-- 10 files changed, 147 insertions(+), 4 deletions(-) create mode 100644 doc/_static/dark-exasol-logo.svg create mode 100644 doc/_static/light-exasol-logo.svg create mode 100644 doc/_templates/partials/webfonts.html create mode 100644 doc/_templates/version.html create mode 100644 doc/conf.py create mode 100644 doc/developer_guide/developer_guide.rst create mode 100644 doc/faq.rst create mode 100644 doc/index.rst diff --git a/doc/_static/dark-exasol-logo.svg b/doc/_static/dark-exasol-logo.svg new file mode 100644 index 0000000..68109cc --- /dev/null +++ b/doc/_static/dark-exasol-logo.svg @@ -0,0 +1 @@ + diff --git a/doc/_static/light-exasol-logo.svg b/doc/_static/light-exasol-logo.svg new file mode 100644 index 0000000..3eec34e --- /dev/null +++ b/doc/_static/light-exasol-logo.svg @@ -0,0 +1,7 @@ + diff --git a/doc/_templates/partials/webfonts.html b/doc/_templates/partials/webfonts.html new file mode 100644 index 0000000..e69de29 diff --git a/doc/_templates/version.html b/doc/_templates/version.html new file mode 100644 index 0000000..7c3e4f6 --- /dev/null +++ b/doc/_templates/version.html @@ -0,0 +1,12 @@ +{% if versions %} +

{{ _('Versions') }}

+
    + {%- for item in versions | reverse %} + {%- if item.name == "main" %} +
  • latest
    • + {%- else %} +
  • {{ item.name }}
    • + {%- endif %} + {%- endfor %} +
+{% endif %} \ No newline at end of file diff --git a/doc/changes/changelog.md b/doc/changes/changelog.md index 862ccfa..7226d73 100644 --- a/doc/changes/changelog.md +++ b/doc/changes/changelog.md @@ -5,3 +5,15 @@ * [0.3.0](changes_0.3.0.md) * [0.2.0](changes_0.2.0.md) * [0.1.0](changes_0.1.0.md) + + +```{toctree} +--- +hidden: +--- +unreleased +changes_0.4.0 +changes_0.3.0 +changes_0.2.0 +changes_0.1.0 +``` diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..0cc0804 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,78 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys + +sys.path.insert(0, os.path.abspath("../")) + +# -- Project information ----------------------------------------------------- + +project = "Error Reporting Python" +copyright = "2022, Exasol" # pylint: disable=redefined-builtin +author = "Exasol" + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "sphinx.ext.todo", + "sphinx.ext.autodoc", + "sphinx.ext.viewcode", + "sphinx.ext.napoleon", + "sphinx.ext.intersphinx", + "sphinx.ext.autosummary", + "sphinx_copybutton", + "myst_parser", + "sphinx_design", +] + +intersphinx_mapping = {"python": ("https://docs.python.org/3", None)} + +# Make sure the target is unique +source_suffix = { + ".rst": "restructuredtext", + ".txt": "markdown", + ".md": "markdown", +} + +todo_include_todos = True + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".build-docu"] + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "shibuya" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] +html_title = "Toolbox" +html_theme_options = { + "light_logo": "_static/light-exasol-logo.svg", + "dark_logo": "_static/dark-exasol-logo.svg", + "github_url": "https://github.com/exasol/error-reporting-python", + "accent_color": "grass", +} + diff --git a/doc/developer_guide/developer_guide.rst b/doc/developer_guide/developer_guide.rst new file mode 100644 index 0000000..cf18c40 --- /dev/null +++ b/doc/developer_guide/developer_guide.rst @@ -0,0 +1,2 @@ +Developer Guide +=============== diff --git a/doc/faq.rst b/doc/faq.rst new file mode 100644 index 0000000..a9f3291 --- /dev/null +++ b/doc/faq.rst @@ -0,0 +1,4 @@ +.. _faq: + +FAQ +=== diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..acd4e02 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,27 @@ +Documentation of the Exasol-Toolbox +----------------------------------- + + +.. grid:: 1 1 3 2 + :gutter: 2 + :padding: 0 + :class-container: surface + + .. grid-item-card:: :octicon:`question` FAQ + :link: faq + :link-type: ref + + Frequently asked questsions. + + +.. toctree:: + :maxdepth: 1 + :hidden: + + user_guide/user_guide + developer_guide/developer_guide + dependencies + faq + changes/changelog + + diff --git a/doc/user_guide/user_guide.md b/doc/user_guide/user_guide.md index e8860c0..a1f4272 100644 --- a/doc/user_guide/user_guide.md +++ b/doc/user_guide/user_guide.md @@ -13,7 +13,7 @@ Please keep in mind that error-code should satisfy the error-code format (see [c Flexibility is provided by introducing placeholder parameters to the error message. -#### code +### 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, @@ -28,15 +28,15 @@ Examples of valide error codes: - 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. -#### 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 +### 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. From 9ea443ac11e76035f6c93ae35bb19096d200007e Mon Sep 17 00:00:00 2001 From: Nicola Coretti Date: Thu, 6 Jun 2024 16:05:55 +0200 Subject: [PATCH 06/10] Configure style and lint settings --- pyproject.toml | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/pyproject.toml b/pyproject.toml index 916b308..cb918d4 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -37,3 +37,41 @@ build-backend = "poetry.core.masonry.api" [tool.poetry.scripts] ec = 'exasol.error._cli:main' + + +[tool.coverage.run] +relative_files = true +source = [ + "exasol", +] + +[tool.coverage.report] +fail_under = 65 + + +[tool.black] +line-length = 88 +verbose = false +include = "\\.pyi?$" + + +[tool.isort] +profile = "black" +force_grid_wrap = 2 + + +[tool.pylint.master] +fail-under = 7.2 + +[tool.pylint.format] +max-line-length = 88 +max-module-lines = 800 + + +[[tool.mypy.overrides]] +module = [ + "exasol.toolbox.sphinx.multiversion.*", + "test.unit.*", + "test.integration.*", +] +ignore_errors = true From b79233685840c8dfed0d26a30b5536733e3415b9 Mon Sep 17 00:00:00 2001 From: Nicola Coretti Date: Fri, 7 Jun 2024 10:13:06 +0200 Subject: [PATCH 07/10] Update .gitignore --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index e14144b..02bea55 100644 --- a/.gitignore +++ b/.gitignore @@ -137,3 +137,6 @@ poetry.lock # Sphinx doc/_build .html-documentation + +.lint.json +.lint.txt From b576e1cd1215690fdef307957632abcdec39ca61 Mon Sep 17 00:00:00 2001 From: Nicola Coretti Date: Fri, 7 Jun 2024 10:13:26 +0200 Subject: [PATCH 08/10] Update project settings --- pyproject.toml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index cb918d4..a297f74 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -29,7 +29,7 @@ python = "^3.8" [tool.poetry.group.dev.dependencies] pytest = "^7.1.2" prysk = {extras = ["pytest-plugin"], version = ">=0.15.1"} -exasol-toolbox = ">=0.12.0" +exasol-toolbox = ">=0.13.0" [build-system] requires = ["poetry-core>=1.0.0"] @@ -61,7 +61,7 @@ force_grid_wrap = 2 [tool.pylint.master] -fail-under = 7.2 +fail-under = 7.0 [tool.pylint.format] max-line-length = 88 From d340eb1ac83b4b59cac6f98137e57c8d67373627 Mon Sep 17 00:00:00 2001 From: Nicola Coretti Date: Fri, 7 Jun 2024 10:13:39 +0200 Subject: [PATCH 09/10] Add gh-pages workflow --- .github/workflows/gh-pages.yml | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 .github/workflows/gh-pages.yml diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml new file mode 100644 index 0000000..c0cbb60 --- /dev/null +++ b/.github/workflows/gh-pages.yml @@ -0,0 +1,27 @@ +name: Publish Documentation + +on: workflow_call + +jobs: + + documentation-job: + runs-on: ubuntu-latest + + steps: + - name: SCM Checkout + uses: actions/checkout@v3 + + - name: Setup Python & Poetry Environment + uses: exasol/python-toolbox/.github/actions/python-environment@0.13.0 + + - name: Build Documentation + run: | + poetry run python -m nox -s build-docs + + - name: Deploy + uses: JamesIves/github-pages-deploy-action@v4.6.0 + with: + branch: gh-pages + folder: .html-documentation + git-config-name: Github Action + git-config-email: opensource@exasol.com From d93739eefe485184a2a7710a7cd266fca751df39 Mon Sep 17 00:00:00 2001 From: Nicola Coretti Date: Fri, 7 Jun 2024 10:14:58 +0200 Subject: [PATCH 10/10] Add pr-merge workflow --- .github/workflows/pr-merge.yml | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 .github/workflows/pr-merge.yml diff --git a/.github/workflows/pr-merge.yml b/.github/workflows/pr-merge.yml new file mode 100644 index 0000000..ca82392 --- /dev/null +++ b/.github/workflows/pr-merge.yml @@ -0,0 +1,14 @@ +name: PR-Merge + +on: + push: + branches: + - 'main' + - 'master' + +jobs: + + publish-docs: + name: Publish Documentation + uses: ./.github/workflows/gh-pages.yml +