Merge pull request #2160 from strictdoc-project/stanislaw/lint_d

Code climate: lint/ruff: activate many checks from the D group

Author: stanislaw

ruff.toml

@@ -14,7 +14,8 @@ select = [
   # Not clear if this check is useful. Too many commas everywhere.
   # "COM",
 
-  # "D",
+  "D",
+
   # "DTZ",
   # "E",
   "EXE",
@@ -54,7 +55,61 @@ ignore = [
     # X is too complex
     "C901",
 
-    "E501",  # (line length violations).
+    # FIXME: Would be great to enable these at some point.
+    # Missing docstring in public module
+    "D100",
+    # Missing docstring in public class
+    "D101",
+    # Missing docstring in public method
+    "D102",
+    # Missing docstring in public function
+    "D103",
+    # Missing docstring in public package
+    "D104",
+    # Missing docstring in magic method
+    "D105",
+    # Missing docstring in public nested class
+    "D106",
+    # Missing docstring in `__init__`
+    "D107",
+
+    # One-line docstring should fit on one line
+    "D200",
+
+    # No blank lines allowed after function docstring (found {num_lines})
+    "D202",
+
+    # 1 blank line required before class docstring
+    "D203",
+
+    # FIXME: 1 blank line required between summary line and description
+    "D205",
+
+    # Multi-line docstring summary should start at the first line
+    "D212",
+
+    # FIXME: This is nice to enable but some test fixtures will need to be fixed.
+    # First line should end with a period
+    "D400",
+
+    # FIXME: First line of docstring should be in imperative mood: "Some text."
+    "D401",
+
+    # FIXME: Enable at some point: First word of the docstring should not be "This"
+    "D404",
+
+    # No blank lines allowed between a section header and its content
+    "D412",
+
+    # Missing blank line after last section ("Examples")
+    "D413",
+
+    # FIXME: This is nice to enable but some test fixtures will need to be fixed.
+    # First line should end with a period, question mark, or exclamation point
+    "D415",
+
+    # Line length violations. This is handled by Ruff format.
+    "E501",
 
     # A warning by ruff format:
     # warning: The following rules may cause conflicts when used with the formatter: `ISC001`.
@@ -75,7 +130,7 @@ ignore = [
     # Too many statements
     "PLR0915",
 
-    # TBD: Enable: Use `sys.exit()` instead of `exit`
+    # FIXME: Enable: Use `sys.exit()` instead of `exit`
     "PLR1722",
 
     # Magic value used in comparison

strictdoc/backend/excel/import_/excel_sheet_proxy.py

@@ -35,7 +35,7 @@ def __init__(self, file: str):
 
     @property
     def name(self) -> str:
-        """returns the name of the first sheet"""
+        """Returns the name of the first sheet"""
         if self.lib == ExcelLibType.OPENPYXL:
             return str(self.sheet.title)
         elif self.lib == ExcelLibType.XLRD:
@@ -44,7 +44,7 @@ def name(self) -> str:
 
     @property
     def ncols(self) -> int:
-        """the number of columns"""
+        """The number of columns"""
         ncols: int = 0
         if self.lib == ExcelLibType.OPENPYXL:
             ncols = self.sheet.max_column
@@ -54,7 +54,7 @@ def ncols(self) -> int:
 
     @property
     def nrows(self) -> int:
-        """the number of rows"""
+        """The number of rows"""
         nrows: int = 0
         if self.lib == ExcelLibType.OPENPYXL:
             nrows = self.sheet.max_row
@@ -63,7 +63,7 @@ def nrows(self) -> int:
         return nrows
 
     def get_cell_value(self, row: int, col: int) -> str:
-        """returns the value at row/col as string"""
+        """Returns the value at row/col as string"""
         cell_value: str = ""
         if self.lib == ExcelLibType.OPENPYXL:
             cell_value = (
@@ -74,7 +74,7 @@ def get_cell_value(self, row: int, col: int) -> str:
         return cell_value
 
     def row_values(self, row: int) -> List[str]:
-        """returns a full row as list"""
+        """Returns a full row as list"""
         row_values: List[str] = []
         if self.lib == ExcelLibType.OPENPYXL:
             row_values = [(cell.value or "") for cell in self.sheet[row + 1]]

strictdoc/helpers/ordered_set.py

@@ -6,7 +6,8 @@
 
 
 class OrderedSet(t.MutableSet[T]):
-    """A set that preserves insertion order by internally using a dict.
+    """
+    A set that preserves insertion order by internally using a dict.
 
     >>> OrderedSet([1, 2, "foo"])
 

tests/end2end/helpers/components/node/document_root.py

@@ -20,24 +20,29 @@ def assert_is_root_node(self) -> None:
         )
 
     def assert_root_node_is_editable(self) -> None:
-        """For the root node.
+        """
+        For the root node.
+
         Should have the attribute and the menu button (may be invisible).
         """
+
         # should have the attribute
         self.test_case.assert_attribute(
             f"{self.node_xpath}",
             "data-editable_node",
             "on",
             by=By.XPATH,
         )
+
         # should have the menu button (may be invisible)
         self.test_case.assert_element_present(
             f"{self.node_xpath}//*[@data-testid='document-edit-config-action']",
             by=By.XPATH,
         )
 
-    # Assert fields content: named methods
-
+    #
+    # Assert fields content: named methods.
+    #
     def assert_document_title_contains(self, text: str) -> None:
         assert isinstance(text, str)
         self.test_case.assert_element(

tests/end2end/helpers/components/node/node.py

@@ -30,7 +30,8 @@ def create_from_node_number(test_case: BaseCase, node_order: int = 2):
         return Node(test_case=test_case, node_xpath=xpath)
 
     def assert_node_is_editable(self) -> None:
-        """It makes sense for section & requirements nodes.
+        """
+        It makes sense for section & requirements nodes.
         Should have the attribute and the menu button (may be invisible).
 
         The root node has its own method from DocumentRoot(Node):
@@ -50,7 +51,8 @@ def assert_node_is_editable(self) -> None:
         )
 
     def assert_node_is_not_editable(self) -> None:
-        """It makes sense for section & requirements nodes (due to 'testid').
+        """
+        It makes sense for section & requirements nodes (due to 'testid').
         Should not have the menu button (might be invisible).
         """
         self.test_case.assert_element_not_present(
@@ -59,7 +61,8 @@ def assert_node_is_not_editable(self) -> None:
         )
 
     def assert_node_is_deletable(self) -> None:
-        """It makes sense for section & requirements nodes.
+        """
+        It makes sense for section & requirements nodes.
         Should have the menu delete button (may be invisible).
         """
         self.test_case.assert_element_present(
@@ -68,7 +71,8 @@ def assert_node_is_deletable(self) -> None:
         )
 
     def assert_node_is_not_deletable(self) -> None:
-        """It makes sense for all nodes.
+        """
+        It makes sense for all nodes.
         Should not have the menu delete button (may be invisible).
         """
         self.test_case.assert_element_not_present(
@@ -77,7 +81,8 @@ def assert_node_is_not_deletable(self) -> None:
         )
 
     def assert_node_has_menu(self) -> None:
-        """It makes sense for all nodes.
+        """
+        It makes sense for all nodes.
         Should have the menu add button (may be invisible).
         """
         self.test_case.assert_element_present(
@@ -86,7 +91,8 @@ def assert_node_has_menu(self) -> None:
         )
 
     def assert_node_has_not_menu(self) -> None:
-        """It makes sense for all nodes.
+        """
+        It makes sense for all nodes.
         Should not have the menu add button (may be invisible).
         """
         self.test_case.assert_element_not_present(
@@ -103,7 +109,8 @@ def assert_node_does_not_contain(self, text: str) -> None:
     # Node delete
 
     def _get_node_delete_confirm(self) -> Confirm:
-        """Need to be confirmed. For full confirmed action, use do_delete_node.
+        """
+        Need to be confirmed. For full confirmed action, use do_delete_node.
 
         Returns:
             Confirm.
@@ -167,14 +174,17 @@ def do_open_form_edit_included_document(self) -> Form_EditIncludedDocument:
         self._do_node_edit()
         return Form_EditIncludedDocument(self.test_case)
 
-    # title string pattern
-
+    #
+    # Title string pattern.
+    #
     def create_node_title_string(
         self,
         node_title: str,
         node_level: str = "",
     ) -> str:
-        """title pattern: "1.2.3.&nbsp:Title".
+        """
+        Title pattern: "1.2.3.&nbsp:Title".
+
         To check in numbered nodes: sections and requirements.
 
         Args:

tests/end2end/helpers/components/node/requirement.py

@@ -48,11 +48,14 @@ def assert_is_requirement(self) -> None:
             by=By.XPATH,
         )
 
-    # requirement style
-
+    #
+    # Requirement style.
+    #
     def assert_requirement_style_simple(self) -> None:
-        """Make sure that the normal (not table-based) requirement
-        is rendered."""
+        """
+        Make sure that the normal (not table-based) requirement
+        is rendered.
+        """
         self.test_case.assert_element(
             f"{self.node_xpath}"
             '//sdoc-requirement[@data-testid="requirement-style-simple"]',

tests/end2end/helpers/screens/screen.py

@@ -88,13 +88,16 @@ def get_requirement(self, node_order: int = 1) -> Requirement:
         return self.get_node(node_order)
 
     def get_node(self, node_order: int = 1) -> Requirement:
-        """Based on "//sdoc-node[@data-testid='node-requirement']" """
+        """
+        Based on "//sdoc-node[@data-testid='node-requirement']"
+        """
         requirement = Requirement.with_node(self.test_case, node_order)
         requirement.assert_is_requirement()
         return requirement
 
     def get_requirement_modal(self, node_order: int = -1) -> Requirement:
-        """Based on "//sdoc-requirement". Searches for an <sdoc-requirement>
+        """
+        Based on "//sdoc-requirement". Searches for an <sdoc-requirement>
         without taking the node <sdoc-node> into account.
 
         Args:
@@ -110,7 +113,9 @@ def get_requirement_modal(self, node_order: int = -1) -> Requirement:
         requirement.assert_is_requirement()
         return requirement
 
+    #
     # TOC
+    #
     def get_toc(self) -> TOC:
         TOC(self.test_case).assert_is_toc()
         return TOC(self.test_case)
@@ -121,7 +126,9 @@ def assert_toc_contains(self, string: str) -> None:
     def assert_toc_contains_not(self, string: str) -> None:
         TOC(self.test_case).assert_toc_contains_not(string)
 
+    #
     # CollapsibleList
+    #
     def get_collapsible_list(self) -> CollapsibleList:
         CollapsibleList(self.test_case).assert_is_collapsible()
         return CollapsibleList(self.test_case)

tests/integration/features/file_traceability/_language_parsers/python/05_python_class/file.py

@@ -2,6 +2,7 @@ class Foo:
     """
     @relation(REQ-1, scope=class)
     """
+
     def hello_world(self):
         print("hello world")  # noqa: T201
         print("hello world")  # noqa: T201

tests/integration/features/file_traceability/_language_parsers/python/05_python_class/test.itest

@@ -6,16 +6,16 @@ CHECK: Published: Hello world doc
 RUN: %check_exists --file "%S/Output/html/_source_files/file.py.html"
 
 RUN: %cat %S/Output/html/%THIS_TEST_FOLDER/input.html | filecheck %s --check-prefix CHECK-HTML
-CHECK-HTML: <a{{.*}}href="../_source_files/file.py.html#REQ-1#1#8">
-CHECK-HTML: <a{{.*}}href="../_source_files/file.py.html#REQ-2#1#8">
+CHECK-HTML: <a{{.*}}href="../_source_files/file.py.html#REQ-1#1#9">
+CHECK-HTML: <a{{.*}}href="../_source_files/file.py.html#REQ-2#1#9">
 
 RUN: %cat %S/Output/html/_source_files/file.py.html | filecheck %s --check-prefix CHECK-SOURCE-FILE
-CHECK-SOURCE-FILE: href="../_source_files/file.py.html#REQ-1#1#8"
-CHECK-SOURCE-FILE: <b>[ 1-8 ]</b>
+CHECK-SOURCE-FILE: href="../_source_files/file.py.html#REQ-1#1#9"
+CHECK-SOURCE-FILE: <b>[ 1-9 ]</b>
 CHECK-SOURCE-FILE: file.py, class Foo
 
-CHECK-SOURCE-FILE: href="../_source_files/file.py.html#REQ-2#1#8"
-CHECK-SOURCE-FILE: <b>[ 1-8 ]</b>
+CHECK-SOURCE-FILE: href="../_source_files/file.py.html#REQ-2#1#9"
+CHECK-SOURCE-FILE: <b>[ 1-9 ]</b>
 CHECK-SOURCE-FILE: file.py, class Foo
 
 RUN: %cat %S/Output/html/source_coverage.html | filecheck %s --check-prefix CHECK-SOURCE-COVERAGE

tests/integration/features/file_traceability/file_roles/01_relations_with_role/file.py

@@ -1,10 +1,12 @@
 class Foo:
     """@relation(REQ-001, scope=class, role=Implementation)"""
+
     pass
 
 
 def foo():
     """@relation(REQ-001, scope=function, role=Implementation)"""
+
     pass