From dd13068eb554ca67e09f2c42e32b05d49936a173 Mon Sep 17 00:00:00 2001
From: Azure Devops <joey.vagedes@gmail.com>
Date: Fri, 28 Oct 2022 09:15:45 -0700
Subject: [PATCH] Add Pydocstyle linting requirements

Adds Pydocstyle linting requirements using the google convention by
adding this linting to the PR gate. Updates developing.md documentation
and adds Pydocstyle linting to the vscode settings.
---
 .pydocstyle                                   |  2 ++
 .vscode/settings.json                         |  3 ++-
 azure-pipelines/templates/build-test-job.yml  |  2 ++
 .../templates/pydocstyle-test-steps.yml       | 27 +++++++++++++++++++
 docs/developing.md                            | 16 +++++++----
 requirements.txt                              |  1 +
 6 files changed, 45 insertions(+), 6 deletions(-)
 create mode 100644 .pydocstyle
 create mode 100644 azure-pipelines/templates/pydocstyle-test-steps.yml

diff --git a/.pydocstyle b/.pydocstyle
new file mode 100644
index 000000000..0b6c5f94b
--- /dev/null
+++ b/.pydocstyle
@@ -0,0 +1,2 @@
+[pydocstyle]
+convention = google
\ No newline at end of file
diff --git a/.vscode/settings.json b/.vscode/settings.json
index fb2c4858b..6fcc90041 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -9,5 +9,6 @@
   "python.testing.pytestEnabled": false,
   "python.testing.unittestEnabled": true,
   "python.linting.flake8Enabled": true,
-  "python.linting.enabled": true
+  "python.linting.enabled": true,
+  "python.linting.pydocstyleEnabled": true
 }
diff --git a/azure-pipelines/templates/build-test-job.yml b/azure-pipelines/templates/build-test-job.yml
index 23f501bca..6bb1f8770 100644
--- a/azure-pipelines/templates/build-test-job.yml
+++ b/azure-pipelines/templates/build-test-job.yml
@@ -33,6 +33,8 @@ jobs:
 
   - template: flake8-test-steps.yml
 
+  - template: pydocstyle-test-steps.yml
+
   - template: spell-test-steps.yml
 
   - template: markdown-lint-steps.yml
diff --git a/azure-pipelines/templates/pydocstyle-test-steps.yml b/azure-pipelines/templates/pydocstyle-test-steps.yml
new file mode 100644
index 000000000..cb30f1bc9
--- /dev/null
+++ b/azure-pipelines/templates/pydocstyle-test-steps.yml
@@ -0,0 +1,27 @@
+# File pydocstyle-test-steps.yml
+#
+# template file to run pydocstyle and if error publish log
+#
+# Copyright (c) Microsoft Corporation
+# SPDX-License-Identifier: BSD-2-Clause-Patent
+##
+
+parameters:
+  none: ''
+  
+steps:
+- script: pydocstyle .
+  displayName: 'Run pydocstyle'
+  condition: succeededOrFailed()
+
+# Only capture and archive the lint log on failures.
+- script: pydocstyle . > pydocstyle.err.log
+  displayName: 'Capture pydocstyle failures'
+  condition: Failed()
+
+- task: PublishBuildArtifacts@1
+  inputs:
+    pathtoPublish: 'pydocstyle.err.log' 
+    artifactName: 'Pydocstyle Error log file'
+  continueOnError: true
+  condition: Failed()
\ No newline at end of file
diff --git a/docs/developing.md b/docs/developing.md
index 5b04e8d14..0b3161eec 100644
--- a/docs/developing.md
+++ b/docs/developing.md
@@ -94,13 +94,19 @@ out all the different parts.
     (whitespace, indentation, etc). In VSCode open the py file and use
     ++alt+shift+f++ to auto format.
 
-2. Run the `BasicDevTests.py` script to check file encoding, file naming, etc
+2. Run a Basic Python docstring Check (using pydocstring) and resolve any issues
+
+    ``` cmd
+    pydocstyle .
+    ```
+
+3. Run the `BasicDevTests.py` script to check file encoding, file naming, etc
 
     ```cmd
     BasicDevTests.py
     ```
 
-3. Run pytest with coverage data collected
+4. Run pytest with coverage data collected
 
     ``` cmd
     pytest -v --junitxml=test.junit.xml --html=pytest_report.html --self-contained-html --cov=edk2toolext --cov-report html:cov_html --cov-report xml:cov.xml --cov-config .coveragerc
@@ -112,17 +118,17 @@ out all the different parts.
     Coverage is uploaded to `codecov.io`. For more information, review
     `coverage.md` in the docs folder.
 
-4. Look at the reports
+5. Look at the reports
     * pytest_report.html
     * cov_html/index.html
 
-5. Run the spell checker
+6. Run the spell checker
 
     ```cmd
     cspell -c .cspell.json "**/*.py" "**/*.md"
     ```
 
-6. Run the markdown linter
+7. Run the markdown linter
 
     ```cmd
     markdownlint "**/*.md"
diff --git a/requirements.txt b/requirements.txt
index 015682fba..9f67b1910 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -2,6 +2,7 @@ pytest == 7.1.2
 pytest-html == 3.1.1
 pytest-cov == 3.0.0
 flake8 == 5.0.4
+pydocstyle == 6.1.1
 pyopenssl == 22.0.0
 pefile == 2022.5.30
 semantic_version == 2.10.0