From 91596b07cf2eaad50d49ef2bbd23a58dee2f3a05 Mon Sep 17 00:00:00 2001 From: Nicola Coretti Date: Fri, 7 Jun 2024 12:10:51 +0200 Subject: [PATCH] Add basic exasol-toolbox support to project (#32) --- .github/workflows/gh-pages.yml | 27 +++++++++ .github/workflows/pr-merge.yml | 14 +++++ .gitignore | 4 ++ 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 +-- noxconfig.py | 20 +++++++ noxfile.py | 8 +++ pyproject.toml | 43 +++++++++++++- 16 files changed, 261 insertions(+), 6 deletions(-) create mode 100644 .github/workflows/gh-pages.yml create mode 100644 .github/workflows/pr-merge.yml 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 create mode 100644 noxconfig.py create mode 100644 noxfile.py 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 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 + diff --git a/.gitignore b/.gitignore index 284db3d..02bea55 100644 --- a/.gitignore +++ b/.gitignore @@ -136,3 +136,7 @@ poetry.lock # Sphinx doc/_build +.html-documentation + +.lint.json +.lint.txt 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') }}

+ +{% 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. 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() 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"] diff --git a/pyproject.toml b/pyproject.toml index 5dff809..a297f74 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -28,11 +28,50 @@ 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.13.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' + + +[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.0 + +[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