From cad92e17c0b6d37390468cf055a568aaab1b6bb7 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Tue, 17 Sep 2024 16:12:15 -0500 Subject: [PATCH 1/9] Add docstrings to fablib.config module --- fabrictestbed_extensions/fablib/config/config.py | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/fabrictestbed_extensions/fablib/config/config.py b/fabrictestbed_extensions/fablib/config/config.py index de007647..277eacf6 100644 --- a/fabrictestbed_extensions/fablib/config/config.py +++ b/fabrictestbed_extensions/fablib/config/config.py @@ -38,10 +38,18 @@ class ConfigException(Exception): + """ + An exception class to represent configuration errors. + """ + pass class Config: + """ + A class that represents fablib configuration. + """ + LOG_LEVELS = { "DEBUG": logging.DEBUG, "INFO": logging.INFO, @@ -744,6 +752,9 @@ def get_config_pretty_names_dict(self) -> Dict[str, str]: return self.REQUIRED_ATTRS_PRETTY_NAMES def save_config(self): + """ + Write the configuration file. + """ if self.config_file_path is None: print("Config file path not set!") return From 3ba33d52e8dfb3db4a0bf81d3b3e7a1d043c7a40 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Tue, 17 Sep 2024 16:12:40 -0500 Subject: [PATCH 2/9] Add an interrogate configuration https://interrogate.readthedocs.io/ helps to check the project's docstring coverage. --- pyproject.toml | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/pyproject.toml b/pyproject.toml index 94ac3f8a..bc8b89f8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -72,3 +72,16 @@ addopts = "-ra -q" # tests will require some manual setup (namely token acquisition), and # thus we can't run them on CI. testpaths = ["tests/unit/"] + +[tool.interrogate] +ignore-init-method = true +ignore-init-module = true +ignore-magic = true +ignore-module = true +ignore-nested-functions = true +ignore-nested-classes = true +ignore-private = true +ignore-semiprivate = true +omit-covered-files = true +verbose = 0 +exclude = ["tests"] From 15e4e029d2d139b4912627a76c42968bc39899ba Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Tue, 17 Sep 2024 16:25:27 -0500 Subject: [PATCH 3/9] Exclude the old editors module from docstring coverage check --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index bc8b89f8..85562d73 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -84,4 +84,4 @@ ignore-private = true ignore-semiprivate = true omit-covered-files = true verbose = 0 -exclude = ["tests"] +exclude = ["tests", "fabrictestbed_extensions/editors"] From 6a99ac1cc842da8371370c50c7319269558d6d28 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Tue, 17 Sep 2024 16:27:45 -0500 Subject: [PATCH 4/9] Add a GitHub Actions workflow to check docstring coverage --- .github/workflows/docstrings.yml | 34 ++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 .github/workflows/docstrings.yml diff --git a/.github/workflows/docstrings.yml b/.github/workflows/docstrings.yml new file mode 100644 index 00000000..3ca3a9f5 --- /dev/null +++ b/.github/workflows/docstrings.yml @@ -0,0 +1,34 @@ +name: Check docstring coverage + +on: + push: + branches: + - "main" + pull_request: + workflow_dispatch: + +permissions: + contents: read + +jobs: + + checks: + runs-on: ubuntu-latest + + steps: + - name: Check out sources + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.x" + cache: 'pip' # cache pip dependencies + cache-dependency-path: pyproject.toml + + # See https://github.com/JackMcKew/python-interrogate-check + - name: Check docstring coverage with interrogate + uses: JackMcKew/python-interrogate-check@v0.1.2 + with: + path: "fabrictestbed_extensions" + fail-under: "92" From a24c491c695a374a819e011ade796841f725a630 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Tue, 17 Sep 2024 16:31:38 -0500 Subject: [PATCH 5/9] Update changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0deafe35..bb05380a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Missing docstrings in slice module (Issue [#316](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/316)) - Missing docstrings in component module (Issue [#317](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/317)) - Missing docstrings in fablib module (Issue [#319](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/319)) +- Missing docstrings in fablib.config module (Issue [#320](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/320)) ## [1.7.3] - 08/05/2024 ### Fixed From a7a538e41e3769de09036d2432f77ea60be2b63a Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Tue, 17 Sep 2024 17:13:05 -0500 Subject: [PATCH 6/9] Fail interrogate when docstring coverage falls under current status --- pyproject.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/pyproject.toml b/pyproject.toml index 85562d73..42381760 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -84,4 +84,5 @@ ignore-private = true ignore-semiprivate = true omit-covered-files = true verbose = 0 +fail-under = 92.6 exclude = ["tests", "fabrictestbed_extensions/editors"] From 5bc178fb385f486dd22f0e940107e30c1e9279a0 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Tue, 17 Sep 2024 17:18:13 -0500 Subject: [PATCH 7/9] Install and run interrogate with Python The version of interrogate on JackMcKew/python-interrogate-check action is 1.2.0, which is too old. --- .github/workflows/docstrings.yml | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/.github/workflows/docstrings.yml b/.github/workflows/docstrings.yml index 3ca3a9f5..ccf9fa90 100644 --- a/.github/workflows/docstrings.yml +++ b/.github/workflows/docstrings.yml @@ -26,9 +26,11 @@ jobs: cache: 'pip' # cache pip dependencies cache-dependency-path: pyproject.toml - # See https://github.com/JackMcKew/python-interrogate-check + - name: Install interrogate + run: | + python -m pip install --upgrade pip + python -m pip install interrogate==1.7.0 + - name: Check docstring coverage with interrogate - uses: JackMcKew/python-interrogate-check@v0.1.2 - with: - path: "fabrictestbed_extensions" - fail-under: "92" + run: | + python -m interrogate -vv fabrictestbed_extensions From a379448ba14dba8097bfcf116e484ed83ad6dc7b Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Tue, 17 Sep 2024 17:28:27 -0500 Subject: [PATCH 8/9] Rename workflow file --- .../workflows/{docstrings.yml => check_docstring_coverage.yml} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename .github/workflows/{docstrings.yml => check_docstring_coverage.yml} (100%) diff --git a/.github/workflows/docstrings.yml b/.github/workflows/check_docstring_coverage.yml similarity index 100% rename from .github/workflows/docstrings.yml rename to .github/workflows/check_docstring_coverage.yml From fc2fd6c92612720f47a144218d0ec715593b9b80 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Tue, 17 Sep 2024 17:33:07 -0500 Subject: [PATCH 9/9] Add some commentary about the workflow --- .github/workflows/check_docstring_coverage.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.github/workflows/check_docstring_coverage.yml b/.github/workflows/check_docstring_coverage.yml index ccf9fa90..11335a6a 100644 --- a/.github/workflows/check_docstring_coverage.yml +++ b/.github/workflows/check_docstring_coverage.yml @@ -1,3 +1,9 @@ +# A check to ensure that our docstring coverage remains pretty good. +# +# We use interrogate (https://interrogate.readthedocs.io/) to check +# docstring coverage. Settings are under `[tool.interrogate]` section +# of the pyproject.toml file in the top-level directory. + name: Check docstring coverage on: