Pydocstyle Updates (#343)

Updates pipeline to only run on the edk2toolext folder. Updates developing documentation to specify to the user that they should only run pydocstyle on the edk2toolext folder. Adds documentation, rather then noqa to empty package init files.
tianocore · Nov 8, 2022 · fdc72c3 · fdc72c3
1 parent d9b86f0
commit fdc72c3
Show file tree

Hide file tree

Showing 11 changed files with 25 additions and 18 deletions.
diff --git a/BasicDevTests.py b/BasicDevTests.py
@@ -18,7 +18,7 @@
 import re
 
 
-def TestEncodingOk(apath, encodingValue): # noqa
+def TestEncodingOk(apath, encodingValue):
     try:
         with open(apath, "rb") as f_obj:
             f_obj.read().decode(encodingValue)
@@ -29,7 +29,7 @@ def TestEncodingOk(apath, encodingValue): # noqa
     return True
 
 
-def TestFilenameLowercase(apath): # noqa
+def TestFilenameLowercase(apath):
     if apath != apath.lower():
         logging.critical(f"Lowercase failure: file {apath} not lower case path")
         logging.error(f"\n\tLOWERCASE: {apath.lower()}\n\tINPUTPATH: {apath}")
@@ -47,14 +47,14 @@ def PackageAndModuleValidCharacters(apath):
     return True
 
 
-def TestNoSpaces(apath): # noqa
+def TestNoSpaces(apath):
     if " " in apath:
         logging.critical(f"NoSpaces failure: file {apath} has spaces in path")
         return False
     return True
 
 
-def TestRequiredLicense(apath): # noqa
+def TestRequiredLicense(apath):
     licenses = ["SPDX-License-Identifier: BSD-2-Clause-Patent", ]
     try:
         with open(apath, "rb") as f_obj:

diff --git a/azure-pipelines/templates/build-test-job.yml b/azure-pipelines/templates/build-test-job.yml
@@ -34,6 +34,8 @@ jobs:
   - template: flake8-test-steps.yml
 
   - template: pydocstyle-test-steps.yml
+    parameters:
+      root_package_folder: ${{parameters.root_package_folder}}
 
   - template: spell-test-steps.yml
 

diff --git a/azure-pipelines/templates/pydocstyle-test-steps.yml b/azure-pipelines/templates/pydocstyle-test-steps.yml
@@ -7,15 +7,15 @@
 ##
 
 parameters:
-  none: ''
+  root_package_folder: ''
 
 steps:
-- script: pydocstyle .
+- script: pydocstyle ${{parameters.root_package_folder}}
   displayName: 'Run pydocstyle'
   condition: succeededOrFailed()
 
 # Only capture and archive the lint log on failures.
-- script: pydocstyle . > pydocstyle.err.log
+- script: pydocstyle ${{parameters.root_package_folder}} > pydocstyle.err.log
   displayName: 'Capture pydocstyle failures'
   condition: Failed()
 

diff --git a/docs/developing.md b/docs/developing.md
@@ -97,7 +97,7 @@ out all the different parts.
 2. Run a Basic Python docstring Check (using pydocstring) and resolve any issues
 
     ``` cmd
-    pydocstyle .
+    pydocstyle edk2toolext
     ```
 
 3. Run the `BasicDevTests.py` script to check file encoding, file naming, etc

diff --git a/edk2toolext/__init__.py b/edk2toolext/__init__.py
@@ -3,5 +3,7 @@
 #
 # SPDX-License-Identifier: BSD-2-Clause-Patent
 ##
+"""This file exists to satisfy pythons packaging requirements.
 
-# noqa
+Read more: https://docs.python.org/3/reference/import.html#regular-packages
+"""
diff --git a/edk2toolext/bin/__init__.py b/edk2toolext/bin/__init__.py
@@ -3,5 +3,7 @@
 #
 # SPDX-License-Identifier: BSD-2-Clause-Patent
 ##
+"""This file exists to satisfy pythons packaging requirements.
 
-# noqa
+Read more: https://docs.python.org/3/reference/import.html#regular-packages
+"""
diff --git a/edk2toolext/environment/__init__.py b/edk2toolext/environment/__init__.py
@@ -3,5 +3,7 @@
 #
 # SPDX-License-Identifier: BSD-2-Clause-Patent
 ##
+"""This file exists to satisfy pythons packaging requirements.
 
-# noqa
+Read more: https://docs.python.org/3/reference/import.html#regular-packages
+"""
diff --git a/edk2toolext/environment/extdeptypes/__init__.py b/edk2toolext/environment/extdeptypes/__init__.py
@@ -3,5 +3,4 @@
 #
 # SPDX-License-Identifier: BSD-2-Clause-Patent
 ##
-
-# noqa
+"""This package contains the different ext_dep types available in the environment."""
diff --git a/edk2toolext/environment/plugintypes/__init__.py b/edk2toolext/environment/plugintypes/__init__.py
@@ -3,5 +3,4 @@
 #
 # SPDX-License-Identifier: BSD-2-Clause-Patent
 ##
-
-# noqa
+"""This package contains the different plugin types available in the environment."""
diff --git a/edk2toolext/invocables/__init__.py b/edk2toolext/invocables/__init__.py
@@ -3,5 +3,4 @@
 #
 # SPDX-License-Identifier: BSD-2-Clause-Patent
 ##
-
-# noqa
+"""This package contains the different invocables available to the developer."""
diff --git a/edk2toolext/tests/__init__.py b/edk2toolext/tests/__init__.py
@@ -3,5 +3,7 @@
 #
 # SPDX-License-Identifier: BSD-2-Clause-Patent
 ##
+"""This file exists to satisfy pythons packaging requirements.
 
-# noqa
+Read more: https://docs.python.org/3/reference/import.html#regular-packages
+"""