address some missing docstring Pylint warnings

diff --git a/ci/tests.py b/ci/tests.py
index 9fcc6a228586651beaf7c099fb8419b96a298ac2..f59e636f010502a883f634b9bdeb551083ca7c46 100644 (file)
--- a/ci/tests.py
+++ b/ci/tests.py
@@ -142,5 +142,8 @@ def test_existence(binary: str):
   assert shutil.which(binary) is not None
 
 def check_that_tool_does_not_exist(tool, os_id):
+  """
+  validate that the given tool does *not* exist
+  """
   assert shutil.which(tool) is None, f"{tool} has been resurrected in the " \
     f'{os.getenv("build_system")} build on {os_id}. Please remove skip.'

diff --git a/doc/infosrc/jconvert.py b/doc/infosrc/jconvert.py
index c7f4f60214fc447f5bd6e9810afb1b2790a531e1..965f8353a0fce9ac1be834ebef32e0fc2127de1e 100755 (executable)
--- a/doc/infosrc/jconvert.py
+++ b/doc/infosrc/jconvert.py
@@ -1,5 +1,9 @@
 #!/usr/bin/env python3
 
+"""
+convert a json file to an html file
+"""
+
 import argparse
 import json
 
@@ -7,7 +11,7 @@ from json2html import json2html
 
 
 def main(): # pylint: disable=missing-function-docstring
-  parser = argparse.ArgumentParser(description="Converts a json file to a html file")
+  parser = argparse.ArgumentParser(description=__doc__)
   parser.add_argument("input", type=argparse.FileType("rt"), help="Input file")
   parser.add_argument("output", type=argparse.FileType("wt"), help="Output file")
   args = parser.parse_args()

diff --git a/doc/infosrc/templates.py b/doc/infosrc/templates.py
index 799b3529acc4c2cfe5e80caadc965c9a588fe845..63e7c2b6dd2264e369e3276641033b291980f0d9 100644 (file)
--- a/doc/infosrc/templates.py
+++ b/doc/infosrc/templates.py
@@ -1,6 +1,13 @@
+"""
+extension for tweaking Jinja templating environment
+"""
+
 import jinja2
 
 def env():
+  """
+  construct a custom Jinja environment for our doc processing
+  """
   return jinja2.Environment(
       # Load template files from ./templates/
       loader=jinja2.PackageLoader(

diff --git a/dot.demo/gv_test.py b/dot.demo/gv_test.py
index 9d851336366b56e11aeaee3c043ed28945c2c66f..fdcb12bb914a89c55ec675bd677e6895203522d0 100755 (executable)
--- a/dot.demo/gv_test.py
+++ b/dot.demo/gv_test.py
@@ -1,5 +1,9 @@
 #!/usr/bin/env python3
 
+"""
+example usage of Graphviz Python module
+"""
+
 import gv # pylint: disable=import-error
 
 g = gv.digraph("G")

diff --git a/rtest/generate_graph.py b/rtest/generate_graph.py
index 32f228cb9d34aa7dd52eff434741995dcc7e7901..3c00875828d90439300ad10fa40cd3f253c6918b 100755 (executable)
--- a/rtest/generate_graph.py
+++ b/rtest/generate_graph.py
@@ -86,6 +86,10 @@ class Graph:
     out.write("}")
 
 class Result:
+  """
+  outcome of a process’ execution
+  """
+
   TIMEOUT = 124
 
   def __init__(self, status: int, runtime: int, rss: Optional[int] = 0):

diff --git a/rtest/test_misc.py b/rtest/test_misc.py
index 6c44bbea70c0c7f84c050bcb2bf3d5943e74710a..7284f4dabf85d39bb608469ca861c71615fa6531 100644 (file)
--- a/rtest/test_misc.py
+++ b/rtest/test_misc.py
@@ -1,3 +1,7 @@
+"""
+Graphviz miscellaneous test cases
+"""
+
 import json
 import subprocess
 

diff --git a/rtest/test_regression.py b/rtest/test_regression.py
index 4891fdfc00f8df5c3cb064832d4b7e5ea0af19f1..ac4c168ba2ebe799352d13f10e340f4a3508f6a2 100644 (file)
--- a/rtest/test_regression.py
+++ b/rtest/test_regression.py
@@ -1,3 +1,10 @@
+"""
+Graphviz regression tests
+
+The test cases in this file relate to previously observed bugs. A failure of one
+of these indicates that a past bug has been reintroduced.
+"""
+
 import json
 import os
 from pathlib import Path

diff --git a/rtest/test_tools.py b/rtest/test_tools.py
index 4e06508d1ca555b9c49530ab250c933652690034..3c3d13f8e3fa7cba9c27581da15025a42d961b14 100644 (file)
--- a/rtest/test_tools.py
+++ b/rtest/test_tools.py
@@ -1,3 +1,11 @@
+"""
+Graphviz tools tests
+
+The test cases in this file are sanity checks on the various tools in the
+Graphviz suite. A failure of one of these indicates that some basic functional
+property of one of the tools has been broken.
+"""
+
 import os
 import platform
 import re
@@ -51,6 +59,9 @@ import pytest
     "vimdot",
 ])
 def test_tools(tool):
+  """
+  check the help/usage output of the given tool looks correct
+  """
 
   if shutil.which(tool) is None:
     pytest.skip(f"{tool} not available")

diff --git a/tclpkg/gv/examples/layout.py b/tclpkg/gv/examples/layout.py
index f5dd218051671b1a8abf96388b8cfd991c456808..8f0dd2b0ebe63b840a634c223f6ef9b1a09e846d 100755 (executable)
--- a/tclpkg/gv/examples/layout.py
+++ b/tclpkg/gv/examples/layout.py
@@ -1,9 +1,13 @@
 #!/usr/bin/env python3
 
+"""
+example usage of the Graphviz Python module
+"""
+
 import gv # pylint: disable=import-error
 
 
-def main():
+def main(): # pylint: disable=missing-function-docstring
   # create a new empty graph
   G = gv.digraph("G")
   # define a simple graph ( A->B )

diff --git a/tclpkg/gv/examples/simple.py b/tclpkg/gv/examples/simple.py
index eba1e3e791745d6f7cef2adfc779c7f8704b3523..6e09e1398a6c52e72e6bf482fabdc32f5599a10a 100755 (executable)
--- a/tclpkg/gv/examples/simple.py
+++ b/tclpkg/gv/examples/simple.py
@@ -1,5 +1,9 @@
 #!/usr/bin/env python3
 
+"""
+example usage of the Graphviz Python module
+"""
+
 import gv # pylint: disable=import-error
 
 # create a new empty graph

diff --git a/tclpkg/gv/test.py b/tclpkg/gv/test.py
index d2fd9084e8592b3614fcd618f15076c68642ad3f..b7ac82f0fb1bbab672988abb386db9dbb92e6637 100644 (file)
--- a/tclpkg/gv/test.py
+++ b/tclpkg/gv/test.py
@@ -1,5 +1,9 @@
 #!/usr/bin/env python3
 
+"""
+example usage of the Graphviz Python module
+"""
+
 import gv # pylint: disable=import-error
 
 g = gv.digraph("G")

diff --git a/tests/regression_tests/installation/test_installation.py b/tests/regression_tests/installation/test_installation.py
index 0efe6f7b6ede8650eaa45d3f12acd2c5892255fb..b0f59518f9638a953e8767daac27cc43e3eef85d 100644 (file)
--- a/tests/regression_tests/installation/test_installation.py
+++ b/tests/regression_tests/installation/test_installation.py
@@ -1,3 +1,7 @@
+"""
+Graphviz version consistency tests
+"""
+
 import os
 from pathlib import Path
 import subprocess
@@ -5,6 +9,10 @@ import sys
 import pytest
 
 def test_installation():
+  """
+  check that Graphviz reports the expected version number
+  """
+
   expected_version = os.environ.get("GV_VERSION")
 
   # If $GV_VERSION is not set, run the CI step that derives it. This will fail