From b2eedf515c26d37a6957f93734bdd280abc477e4 Mon Sep 17 00:00:00 2001 From: jce Date: Mon, 6 Nov 2023 16:07:54 +0100 Subject: [PATCH 01/14] Add config value cq_description_format --- README.rst | 6 ++++++ src/mlx/regex_checker.py | 2 +- src/mlx/warnings_checker.py | 10 ++++++++++ 3 files changed, 17 insertions(+), 1 deletion(-) diff --git a/README.rst b/README.rst index b3ff442a..e88f1bbf 100644 --- a/README.rst +++ b/README.rst @@ -302,6 +302,7 @@ Configuration file is in JSON or YAML_ format with a simple structure. "sphinx": { "enabled": false, "cq_default_path": "doc/source/conf.py", + "cq_description_format": "{PRODUCT} | {description}", "min": 0, "max": 0 }, @@ -422,9 +423,14 @@ Use `-C, --code-quality` to let the plugin generate `a Code Quality report`_ for Sphinx, Doxygen and XMLRunner will be included. Other checker types are not supported by this feature. The report is a JSON file that implements `a subset of the Code Climate spec`_. Define this file `as a codequality report artifact`_ of the CI job. + If a warning doesn't contain a path, `"cq_default_path"` from the `configuration file to pass options`_ will be used. If not configured, `.gitlab-ci.yml` will be used as a fallback path. +You can customize the description with `"cq_description_format"`, see `configuration file to pass options`_. +Its value should be a Python string template that uses the predefined variable `description`. In addition, +environment variables are also available. + ======================= Issues and New Features ======================= diff --git a/src/mlx/regex_checker.py b/src/mlx/regex_checker.py index ebf8761f..44278c88 100644 --- a/src/mlx/regex_checker.py +++ b/src/mlx/regex_checker.py @@ -61,7 +61,7 @@ def add_code_quality_finding(self, match): groups = {name: result for name, result in match.groupdict().items() if result} for name, result in groups.items(): if name.startswith("description"): - finding["description"] = result + finding["description"] = self.assemble_cq_description(result) break else: return # no description was found, which is the bare minimum diff --git a/src/mlx/warnings_checker.py b/src/mlx/warnings_checker.py index ce84a01a..af91167a 100644 --- a/src/mlx/warnings_checker.py +++ b/src/mlx/warnings_checker.py @@ -1,4 +1,5 @@ import abc +import os import re @@ -20,6 +21,7 @@ def __init__(self, verbose=False): self.cq_findings = [] self.cq_enabled = False self.cq_default_path = '.gitlab-ci.yml' + self.cq_description_format = '{description}' self.exclude_patterns = [] self.include_patterns = [] @@ -28,6 +30,12 @@ def counted_warnings(self): ''' List: list of counted warnings (str) ''' return self._counted_warnings + def assemble_cq_description(self, raw_description): + try: + return self.cq_description_format.format(description=raw_description, **os.environ) + except KeyError as err: + raise ValueError(f"Failed to find environment value while assembling code quality description: {err}") + @abc.abstractmethod def check(self, content): ''' Function for counting the number of warnings in a specific text @@ -154,6 +162,8 @@ def parse_config(self, config): self.add_patterns(config.get("exclude"), self.exclude_patterns) if 'cq_default_path' in config: self.cq_default_path = config['cq_default_path'] + if 'cq_description_format' in config: + self.cq_description_format = config['cq_description_format'] def _is_excluded(self, content): ''' Checks if the specific text must be excluded based on the configured regexes for exclusion and inclusion. From 9419e2932836a240243d08d1dd4f0bcb2fb62200 Mon Sep 17 00:00:00 2001 From: jce Date: Mon, 6 Nov 2023 16:09:11 +0100 Subject: [PATCH 02/14] Test config option cq_description_format --- tests/test_in/code_quality_format.json | 79 +++++++++++++++++++ tests/test_in/config_code_quality_format.json | 31 ++++++++ tests/test_integration.py | 17 ++++ 3 files changed, 127 insertions(+) create mode 100644 tests/test_in/code_quality_format.json create mode 100644 tests/test_in/config_code_quality_format.json diff --git a/tests/test_in/code_quality_format.json b/tests/test_in/code_quality_format.json new file mode 100644 index 00000000..89ca3c02 --- /dev/null +++ b/tests/test_in/code_quality_format.json @@ -0,0 +1,79 @@ +[ + { + "severity": "major", + "location": { + "path": "git/test/index.rst", + "lines": { + "begin": 1 + } + }, + "description": "envvar_value | toctree contains reference to nonexisting document u'installation' (12345)", + "fingerprint": "678c4f093876aed4280445a61e9556bc" + }, + { + "severity": "major", + "location": { + "path": "doc/source/conf.py", + "lines": { + "begin": 1 + } + }, + "description": "envvar_value | List item 'CL-UNDEFINED_CL_ITEM' in merge/pull request 138 is not defined as a checklist-item. (12345)", + "fingerprint": "76989a10d5c1d2cd28080ea2aafa3c04" + }, + { + "severity": "info", + "location": { + "path": "doc/doxygen/Doxyfile", + "lines": { + "begin": 1 + } + }, + "description": "Output directory `doc/doxygen/framework' does not exist. I have created it for you.", + "fingerprint": "256cb9d4b9b3c05ba755e5da30b2afb2" + }, + { + "severity": "critical", + "location": { + "path": "helper/SimpleTimer.h", + "lines": { + "begin": 19 + } + }, + "description": "Unexpected character `\"'", + "fingerprint": "d71d9f49bd308ace916bce3c54f430c6" + }, + { + "severity": "major", + "location": { + "path": "doc/doxygen/Doxyfile", + "lines": { + "begin": 1 + } + }, + "description": "The following parameters of sofa::component::odesolver::EulerKaapiSolver::v_peq(VecId v, VecId a, double f) are not documented:", + "fingerprint": "9c91370059e40eb07289790f2b9d6a75" + }, + { + "severity": "critical", + "location": { + "path": "doc/doxygen/Doxyfile", + "lines": { + "begin": 1 + } + }, + "description": "Could not read image `/home/user/myproject/html/struct_foo_graph.png' generated by dot!", + "fingerprint": "bdd0d0b7cc25b1f4414f630c2351bf3c" + }, + { + "severity": "critical", + "location": { + "path": ".gitlab-ci.yml", + "lines": { + "begin": 1 + } + }, + "description": "test_some_error_test (something.anything.somewhere)'", + "fingerprint": "cd09ae46ee5361570fd59de78b454e11" + } +] diff --git a/tests/test_in/config_code_quality_format.json b/tests/test_in/config_code_quality_format.json new file mode 100644 index 00000000..8f28d183 --- /dev/null +++ b/tests/test_in/config_code_quality_format.json @@ -0,0 +1,31 @@ +{ + "sphinx": { + "enabled": true, + "cq_default_path": "doc/source/conf.py", + "cq_description_format": "{FIRST_ENVVAR} | {description} ({SECOND_ENVVAR})", + "min": 0, + "max": 0 + }, + "doxygen": { + "enabled": true, + "cq_default_path": "doc/doxygen/Doxyfile", + "min": 0, + "max": 0 + }, + "junit": { + "enabled": false + }, + "xmlrunner": { + "enabled": true, + "min": 0, + "max": 0 + }, + "coverity": { + "enabled": true, + "min": 0, + "max": 0 + }, + "robot": { + "enabled": false + } +} diff --git a/tests/test_integration.py b/tests/test_integration.py index 9ec7e310..2d0bb237 100644 --- a/tests/test_integration.py +++ b/tests/test_integration.py @@ -1,4 +1,5 @@ import filecmp +import os from io import StringIO from pathlib import Path from unittest import TestCase @@ -309,3 +310,19 @@ def test_code_quality(self, path_cwd_mock): ]) self.assertEqual(2, retval) self.assertTrue(filecmp.cmp(out_file, ref_file), '{} differs from {}'.format(out_file, ref_file)) + + @patch('pathlib.Path.cwd') + def test_cq_description_format(self, path_cwd_mock): + os.environ['FIRST_ENVVAR'] = 'envvar_value' + os.environ['SECOND_ENVVAR'] = '12345' + path_cwd_mock.return_value = '/home/user/myproject' + filename = 'code_quality_format.json' + out_file = str(TEST_OUT_DIR / filename) + ref_file = str(TEST_IN_DIR / filename) + retval = warnings_wrapper([ + '--code-quality', out_file, + '--config', 'tests/test_in/config_code_quality_format.json', + 'tests/test_in/mixed_warnings.txt', + ]) + self.assertEqual(2, retval) + self.assertTrue(filecmp.cmp(out_file, ref_file), '{} differs from {}'.format(out_file, ref_file)) From 331722d704bb142f0ada4967881d657205ef297f Mon Sep 17 00:00:00 2001 From: jce Date: Mon, 6 Nov 2023 16:16:04 +0100 Subject: [PATCH 03/14] Delete badge of deprecated requires.io --- README.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/README.rst b/README.rst index e88f1bbf..f031f704 100644 --- a/README.rst +++ b/README.rst @@ -30,10 +30,6 @@ :target: https://codeclimate.com/github/melexis/warnings-plugin :alt: Issue Count -.. image:: https://requires.io/github/melexis/warnings-plugin/requirements.svg?branch=master - :target: https://requires.io/github/melexis/warnings-plugin/requirements/?branch=master - :alt: Requirements Status - .. image:: https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat :target: https://github.com/melexis/warnings-plugin/issues :alt: Contributions welcome From b70368cddd41a5ed6438cbfcd2d8d5cc857c359d Mon Sep 17 00:00:00 2001 From: jce Date: Mon, 6 Nov 2023 16:18:16 +0100 Subject: [PATCH 04/14] Test Python 3.12 --- .github/workflows/python-package.yml | 2 +- setup.py | 1 + tox.ini | 4 +++- 3 files changed, 5 insertions(+), 2 deletions(-) diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-package.yml index 55f6efe8..a30fab02 100644 --- a/.github/workflows/python-package.yml +++ b/.github/workflows/python-package.yml @@ -9,7 +9,7 @@ jobs: strategy: fail-fast: false matrix: - python-version: ['3.7', '3.8', '3.9', '3.10', '3.11'] + python-version: ['3.7', '3.8', '3.9', '3.10', '3.11', '3.12'] steps: - uses: actions/checkout@v3 - name: Set up Python ${{ matrix.python-version }} diff --git a/setup.py b/setup.py index 40c1a777..5e33e76b 100644 --- a/setup.py +++ b/setup.py @@ -53,6 +53,7 @@ 'Programming Language :: Python :: 3.9', 'Programming Language :: Python :: 3.10', 'Programming Language :: Python :: 3.11', + 'Programming Language :: Python :: 3.12', # 'Programming Language :: Python :: Implementation :: CPython', # 'Programming Language :: Python :: Implementation :: PyPy', # uncomment if you test on these interpreters: diff --git a/tox.ini b/tox.ini index d4b1204c..68c17fe8 100644 --- a/tox.ini +++ b/tox.ini @@ -2,7 +2,7 @@ envlist = clean, check, - py37, py38, py39, py310, py311 + py37, py38, py39, py310, py311, py312 [gh-actions] python = @@ -11,6 +11,7 @@ python = 3.9: py39 3.10: py310 3.11: py311 + 3.12: py312 [testenv] basepython = @@ -21,6 +22,7 @@ basepython = py39: {env:TOXPYTHON:python3.9} py310: {env:TOXPYTHON:python3.10} py311: {env:TOXPYTHON:python3.11} + py312: {env:TOXPYTHON:python3.12} {lxml_support,bootstrap,spell,docs,check,coverage,report,clean}: python3 setenv = PYTHONPATH={toxinidir}/tests From 40efe43c9fb63e98dbf57effefcf26fa281ccef1 Mon Sep 17 00:00:00 2001 From: jce Date: Mon, 6 Nov 2023 16:31:01 +0100 Subject: [PATCH 05/14] Test error handling when envvar is undefined --- tests/test_integration.py | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/tests/test_integration.py b/tests/test_integration.py index 2d0bb237..ad6fdbf1 100644 --- a/tests/test_integration.py +++ b/tests/test_integration.py @@ -311,6 +311,20 @@ def test_code_quality(self, path_cwd_mock): self.assertEqual(2, retval) self.assertTrue(filecmp.cmp(out_file, ref_file), '{} differs from {}'.format(out_file, ref_file)) + def test_cq_description_format_missing_envvar(self): + os.environ['FIRST_ENVVAR'] = 'envvar_value' + filename = 'code_quality_format.json' + out_file = str(TEST_OUT_DIR / filename) + with self.assertRaises(ValueError) as c_m: + warnings_wrapper([ + '--code-quality', out_file, + '--config', 'tests/test_in/config_code_quality_format.json', + 'tests/test_in/mixed_warnings.txt', + ]) + self.assertEqual( + str(c_m.exception), + "Failed to find environment value while assembling code quality description: 'SECOND_ENVVAR'") + @patch('pathlib.Path.cwd') def test_cq_description_format(self, path_cwd_mock): os.environ['FIRST_ENVVAR'] = 'envvar_value' From 578aa9f349d843a8bf56da3e295f7a855b57aaee Mon Sep 17 00:00:00 2001 From: jce Date: Mon, 6 Nov 2023 16:57:37 +0100 Subject: [PATCH 06/14] Delete any added environment variables --- tests/test_integration.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/tests/test_integration.py b/tests/test_integration.py index ad6fdbf1..645fdda9 100644 --- a/tests/test_integration.py +++ b/tests/test_integration.py @@ -17,6 +17,11 @@ def setUp(self): if not TEST_OUT_DIR.exists(): TEST_OUT_DIR.mkdir() + def tearDown(self): + for var in ('FIRST_ENVVAR', 'SECOND_ENVVAR'): + if var in os.environ: + del os.environ[var] + def test_help(self): with self.assertRaises(SystemExit) as ex: warnings_wrapper(['--help']) From b79516723f8ca77c2eaa91ee993a2b0ba21f47b5 Mon Sep 17 00:00:00 2001 From: jce Date: Tue, 7 Nov 2023 14:26:19 +0100 Subject: [PATCH 07/14] Use string.Template and rename cq_description_format to cq_description_template --- README.rst | 8 ++++---- src/mlx/regex_checker.py | 3 ++- src/mlx/warnings_checker.py | 21 +++++++++++++++------ 3 files changed, 21 insertions(+), 11 deletions(-) diff --git a/README.rst b/README.rst index f031f704..8277c90f 100644 --- a/README.rst +++ b/README.rst @@ -298,7 +298,7 @@ Configuration file is in JSON or YAML_ format with a simple structure. "sphinx": { "enabled": false, "cq_default_path": "doc/source/conf.py", - "cq_description_format": "{PRODUCT} | {description}", + "cq_description_template": "$PRODUCT | $description", "min": 0, "max": 0 }, @@ -423,9 +423,9 @@ of the CI job. If a warning doesn't contain a path, `"cq_default_path"` from the `configuration file to pass options`_ will be used. If not configured, `.gitlab-ci.yml` will be used as a fallback path. -You can customize the description with `"cq_description_format"`, see `configuration file to pass options`_. -Its value should be a Python string template that uses the predefined variable `description`. In addition, -environment variables are also available. +You can customize the description with `"cq_description_template"`, see `configuration file to pass options`_. +Its value should be a template for Python's string.Template. The template should contain `$description` and has access +to all environment variables, e.g. `$HOME`. ======================= Issues and New Features diff --git a/src/mlx/regex_checker.py b/src/mlx/regex_checker.py index 44278c88..5ccbd442 100644 --- a/src/mlx/regex_checker.py +++ b/src/mlx/regex_checker.py @@ -1,4 +1,5 @@ import hashlib +import os import re from pathlib import Path @@ -61,7 +62,7 @@ def add_code_quality_finding(self, match): groups = {name: result for name, result in match.groupdict().items() if result} for name, result in groups.items(): if name.startswith("description"): - finding["description"] = self.assemble_cq_description(result) + finding["description"] = self.cq_description_template.substitute(os.environ, description=result) break else: return # no description was found, which is the bare minimum diff --git a/src/mlx/warnings_checker.py b/src/mlx/warnings_checker.py index af91167a..f8997799 100644 --- a/src/mlx/warnings_checker.py +++ b/src/mlx/warnings_checker.py @@ -1,6 +1,7 @@ import abc import os import re +from string import Template class WarningsChecker: @@ -21,7 +22,7 @@ def __init__(self, verbose=False): self.cq_findings = [] self.cq_enabled = False self.cq_default_path = '.gitlab-ci.yml' - self.cq_description_format = '{description}' + self._cq_description_template = Template('$description') self.exclude_patterns = [] self.include_patterns = [] @@ -30,11 +31,19 @@ def counted_warnings(self): ''' List: list of counted warnings (str) ''' return self._counted_warnings - def assemble_cq_description(self, raw_description): + @property + def cq_description_template(self): + ''' Template: string.Template instance based on the configured template string ''' + return self._cq_description_template + + @cq_description_template.setter + def cq_description_template(self, template_obj): try: - return self.cq_description_format.format(description=raw_description, **os.environ) + template_obj.substitute(os.environ, description='test') except KeyError as err: - raise ValueError(f"Failed to find environment value while assembling code quality description: {err}") + raise ValueError(f"Failed to find environment variable from configuration value " + f"'cq_description_template': {err}") from err + self._cq_description_template = template_obj @abc.abstractmethod def check(self, content): @@ -162,8 +171,8 @@ def parse_config(self, config): self.add_patterns(config.get("exclude"), self.exclude_patterns) if 'cq_default_path' in config: self.cq_default_path = config['cq_default_path'] - if 'cq_description_format' in config: - self.cq_description_format = config['cq_description_format'] + if 'cq_description_template' in config: + self.cq_description_template = Template(config['cq_description_template']) def _is_excluded(self, content): ''' Checks if the specific text must be excluded based on the configured regexes for exclusion and inclusion. From cda72240f51d09543e83822bb792be5c98251ae7 Mon Sep 17 00:00:00 2001 From: jce Date: Tue, 7 Nov 2023 14:34:39 +0100 Subject: [PATCH 08/14] Update test suite after b79516723f8ca77c2eaa91ee993a2b0ba21f47b5 --- ...uality_format.json => config_cq_description_format.json} | 2 +- tests/test_integration.py | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) rename tests/test_in/{config_code_quality_format.json => config_cq_description_format.json} (86%) diff --git a/tests/test_in/config_code_quality_format.json b/tests/test_in/config_cq_description_format.json similarity index 86% rename from tests/test_in/config_code_quality_format.json rename to tests/test_in/config_cq_description_format.json index 8f28d183..091bf92d 100644 --- a/tests/test_in/config_code_quality_format.json +++ b/tests/test_in/config_cq_description_format.json @@ -2,7 +2,7 @@ "sphinx": { "enabled": true, "cq_default_path": "doc/source/conf.py", - "cq_description_format": "{FIRST_ENVVAR} | {description} ({SECOND_ENVVAR})", + "cq_description_template": "$FIRST_ENVVAR | $description ($SECOND_ENVVAR)", "min": 0, "max": 0 }, diff --git a/tests/test_integration.py b/tests/test_integration.py index 645fdda9..95267c8a 100644 --- a/tests/test_integration.py +++ b/tests/test_integration.py @@ -323,12 +323,12 @@ def test_cq_description_format_missing_envvar(self): with self.assertRaises(ValueError) as c_m: warnings_wrapper([ '--code-quality', out_file, - '--config', 'tests/test_in/config_code_quality_format.json', + '--config', 'tests/test_in/config_cq_description_format.json', 'tests/test_in/mixed_warnings.txt', ]) self.assertEqual( str(c_m.exception), - "Failed to find environment value while assembling code quality description: 'SECOND_ENVVAR'") + "Failed to find environment variable from configuration value 'cq_description_template': 'SECOND_ENVVAR'") @patch('pathlib.Path.cwd') def test_cq_description_format(self, path_cwd_mock): @@ -340,7 +340,7 @@ def test_cq_description_format(self, path_cwd_mock): ref_file = str(TEST_IN_DIR / filename) retval = warnings_wrapper([ '--code-quality', out_file, - '--config', 'tests/test_in/config_code_quality_format.json', + '--config', 'tests/test_in/config_cq_description_format.json', 'tests/test_in/mixed_warnings.txt', ]) self.assertEqual(2, retval) From ec109b2cec2cb3943d3455ebd33154a8b4dcd0a5 Mon Sep 17 00:00:00 2001 From: jce Date: Tue, 7 Nov 2023 14:37:44 +0100 Subject: [PATCH 09/14] Substitute environment variables already in setter of cq_description_template --- src/mlx/regex_checker.py | 3 +-- src/mlx/warnings_checker.py | 2 +- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/src/mlx/regex_checker.py b/src/mlx/regex_checker.py index 5ccbd442..1230a37b 100644 --- a/src/mlx/regex_checker.py +++ b/src/mlx/regex_checker.py @@ -1,5 +1,4 @@ import hashlib -import os import re from pathlib import Path @@ -62,7 +61,7 @@ def add_code_quality_finding(self, match): groups = {name: result for name, result in match.groupdict().items() if result} for name, result in groups.items(): if name.startswith("description"): - finding["description"] = self.cq_description_template.substitute(os.environ, description=result) + finding["description"] = self.cq_description_template.substitute(description=result) break else: return # no description was found, which is the bare minimum diff --git a/src/mlx/warnings_checker.py b/src/mlx/warnings_checker.py index f8997799..86c7e4c9 100644 --- a/src/mlx/warnings_checker.py +++ b/src/mlx/warnings_checker.py @@ -39,7 +39,7 @@ def cq_description_template(self): @cq_description_template.setter def cq_description_template(self, template_obj): try: - template_obj.substitute(os.environ, description='test') + template_obj.template = template_obj.substitute(os.environ, description='$description') except KeyError as err: raise ValueError(f"Failed to find environment variable from configuration value " f"'cq_description_template': {err}") from err From 38981038b9aa7126c02eff505534bc7c98227e55 Mon Sep 17 00:00:00 2001 From: jce Date: Tue, 7 Nov 2023 14:41:31 +0100 Subject: [PATCH 10/14] Link to docs of string.Template --- README.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 8277c90f..6af21e09 100644 --- a/README.rst +++ b/README.rst @@ -424,7 +424,7 @@ If a warning doesn't contain a path, `"cq_default_path"` from the `configuration If not configured, `.gitlab-ci.yml` will be used as a fallback path. You can customize the description with `"cq_description_template"`, see `configuration file to pass options`_. -Its value should be a template for Python's string.Template. The template should contain `$description` and has access +Its value should be a template for Python's `string.Template`_. The template should contain `$description` and has access to all environment variables, e.g. `$HOME`. ======================= @@ -447,3 +447,4 @@ development of the plugin. We encourage anyone to contribute to our repository. .. _a Code Quality report: https://docs.gitlab.com/ee/ci/testing/code_quality.html .. _a subset of the Code Climate spec: https://docs.gitlab.com/ee/ci/testing/code_quality.html#implement-a-custom-tool .. _as a codequality report artifact: https://docs.gitlab.com/ee/ci/yaml/artifacts_reports.html#artifactsreportscodequality +.. _string.Template: https://docs.python.org/3/library/string.html#string.Template.template From 650358fd9f269e9d46bf2cd4c7462f63a380e47a Mon Sep 17 00:00:00 2001 From: jce Date: Tue, 7 Nov 2023 14:59:32 +0100 Subject: [PATCH 11/14] Use double backticks for GitHub's rendering of RST --- README.rst | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/README.rst b/README.rst index 6af21e09..ac261d1b 100644 --- a/README.rst +++ b/README.rst @@ -105,9 +105,9 @@ Running Command --------------- There are few ways to run warnings plugin. If you are playing with Python on -your computer you want to use `virtualenv`. This will separate your packages +your computer you want to use ``virtualenv``. This will separate your packages per project and there is less chance of some dependency hell. You can -initialize virtual environment in current directory by `virtualenv .` . +initialize virtual environment in current directory by ``virtualenv .`` . Melexis Warnings plugin can be called directly from shell/console using: @@ -115,7 +115,7 @@ Melexis Warnings plugin can be called directly from shell/console using: mlx-warnings -h -It has also possibility to be called as module from `Python3`. In +It has also possibility to be called as module from ``python3``. In that case command will look like: .. code-block:: bash @@ -187,7 +187,7 @@ Parse for Coverity Defects Coverity is a static analysis tool which has option to run desktop analysis on your local changes and report the results back directly in the console. You only need to list affected files and below example lists changed files -between your branch and master, which it then forwards to `cov-run-desktop`: +between your branch and master, which it then forwards to ``cov-run-desktop``: .. code-block:: bash @@ -195,7 +195,7 @@ between your branch and master, which it then forwards to `cov-run-desktop`: You can pipe the results to logfile, which you pass to warnings-plugin, or you use -the `--command` argument and execute the `cov-run-desktop` through +the ``--command`` argument and execute the ``cov-run-desktop`` through .. code-block:: bash @@ -342,11 +342,11 @@ Configuration file is in JSON or YAML_ format with a simple structure. } -First key is `checkername`, then it contains a boolean value for key `enabled`, -value for minimum number of warnings with key `min` and value for maximum -number of warnings with key `max`. This structure allows simple expansion. +First key is ``checkername``, then it contains a boolean value for key ``enabled``, +value for minimum number of warnings with key ``min`` and value for maximum +number of warnings with key ``max``. This structure allows simple expansion. -To run the plugin with configuration file you simply pass `--config` flag with +To run the plugin with configuration file you simply pass ``--config`` flag with path to configuration file .. code-block:: bash @@ -372,7 +372,7 @@ Exclude Matches With Regexes In case you want a checker to exclude certain matches, you can configure one or more regular expressions in the configuration file on a per-checker basis. If a pattern of a regex to exclude is found in a match of the checker's regex, the checker -won't count that match. Add the regex(es) as a list of string values for the `exclude` key. +won't count that match. Add the regex(es) as a list of string values for the ``exclude`` key. An example configuration for the sphinx checker is given below: .. code-block:: json @@ -392,10 +392,10 @@ An example configuration for the sphinx checker is given below: Exclude Sphinx Deprecation Warnings ----------------------------------- -There is a special flag `--exclude-sphinx-deprecation` that lets the sphinx checker exclude +There is a special flag ``--exclude-sphinx-deprecation`` that lets the sphinx checker exclude Sphinx deprecation warnings. These warnings match the following regular expression: -`RemovedInSphinx\\d+Warning`. Using this flag results in the same behavior as adding this -regex to the configuration file as value for the `exclude` key for the sphinx checker. +``RemovedInSphinx\\d+Warning``. Using this flag results in the same behavior as adding this +regex to the configuration file as value for the ``exclude`` key for the sphinx checker. Store All Counted Warnings -------------------------- @@ -415,17 +415,17 @@ Example entries: Code Quality Report ------------------- -Use `-C, --code-quality` to let the plugin generate `a Code Quality report`_ for GitLab CI. All counted +Use ``-C, --code-quality`` to let the plugin generate `a Code Quality report`_ for GitLab CI. All counted Sphinx, Doxygen and XMLRunner will be included. Other checker types are not supported by this feature. The report is a JSON file that implements `a subset of the Code Climate spec`_. Define this file `as a codequality report artifact`_ of the CI job. -If a warning doesn't contain a path, `"cq_default_path"` from the `configuration file to pass options`_ will be used. -If not configured, `.gitlab-ci.yml` will be used as a fallback path. +If a warning doesn't contain a path, ``"cq_default_path"`` from the `configuration file to pass options`_ will be used. +If not configured, ``.gitlab-ci.yml`` will be used as a fallback path. -You can customize the description with `"cq_description_template"`, see `configuration file to pass options`_. -Its value should be a template for Python's `string.Template`_. The template should contain `$description` and has access -to all environment variables, e.g. `$HOME`. +You can customize the description with ``"cq_description_template"``, see `configuration file to pass options`_. +Its value should be a template for Python's ``string.Template``_. The template should contain ``$description`` and has +access to all environment variables, e.g. ``$HOME``. ======================= Issues and New Features From 27e4f9bbb452106f83f60341546303629f28220b Mon Sep 17 00:00:00 2001 From: jce Date: Tue, 7 Nov 2023 15:00:01 +0100 Subject: [PATCH 12/14] Delete useless example: it only caused confusion --- README.rst | 8 -------- 1 file changed, 8 deletions(-) diff --git a/README.rst b/README.rst index ac261d1b..35cdc60f 100644 --- a/README.rst +++ b/README.rst @@ -404,14 +404,6 @@ Use `-o, --output ` to let the plugin write all counted warnings/fail This can help you separate the warnings/failures that matter from those that are excluded or from irrelevant text that may exist in the input file (or produced by the given command). -Example entries: - - Sphinx: - /home/bljah/test/index.rst:5: WARNING: toctree contains reference to nonexisting document u'installation' - - JUnit/RobotFramework: - test_warn_plugin_double_fail.myfirstfai1ure: Is our warnings plugin able to trace this random failure msg? - Code Quality Report ------------------- From 14f1318f7f323f218aa0fab22d1f8d55f7ff9f83 Mon Sep 17 00:00:00 2001 From: Jasper Craeghs <28319872+JasperCraeghs@users.noreply.github.com> Date: Tue, 7 Nov 2023 15:09:52 +0100 Subject: [PATCH 13/14] Fix RST syntax --- README.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 35cdc60f..657776fb 100644 --- a/README.rst +++ b/README.rst @@ -416,7 +416,7 @@ If a warning doesn't contain a path, ``"cq_default_path"`` from the `configurati If not configured, ``.gitlab-ci.yml`` will be used as a fallback path. You can customize the description with ``"cq_description_template"``, see `configuration file to pass options`_. -Its value should be a template for Python's ``string.Template``_. The template should contain ``$description`` and has +Its value should be a template for Python's |string.Template|_. The template should contain ``$description`` and has access to all environment variables, e.g. ``$HOME``. ======================= @@ -435,6 +435,7 @@ Contribute There is a Contribution guide available if you would like to get involved in development of the plugin. We encourage anyone to contribute to our repository. +.. |string.Template| replace:: ``string.Template`` .. _YAML: https://yaml.org/spec/1.2.2/ .. _a Code Quality report: https://docs.gitlab.com/ee/ci/testing/code_quality.html .. _a subset of the Code Climate spec: https://docs.gitlab.com/ee/ci/testing/code_quality.html#implement-a-custom-tool From faa9b1fcb529d5eab53a83ece57db25379209966 Mon Sep 17 00:00:00 2001 From: Jasper Craeghs <28319872+JasperCraeghs@users.noreply.github.com> Date: Tue, 7 Nov 2023 15:12:55 +0100 Subject: [PATCH 14/14] Highlight CLI option as monospace text --- README.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 657776fb..fc2937b7 100644 --- a/README.rst +++ b/README.rst @@ -261,7 +261,7 @@ with command: Parse for Robot Framework Test Failures --------------------------------------- -When running `Robot Framework`_ tests with `--xunit report.xml`_ as an input +When running `Robot Framework`_ tests with |--xunit report.xml|_ as an input argument, an xUnit compatible result file is generated. The warnings-plugin can parse this file and check the amount of failures. By default, the test results of all test suites in the file are taken into account. If you only care about @@ -283,6 +283,7 @@ input file. When this setting is missing, the default value ``true`` is used. python3 -m mlx.warnings --robot --name "Suite Name" report.xml .. _`Robot Framework`: https://robotframework.org/ +.. |--xunit report.xml| replace:: ``--xunit report.xml`` .. _`--xunit report.xml`: https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#xunit-compatible-result-file ----------------------------------