DOCS: Enable subset of pydocstyle rules, bulk update ruff fixes (#3550)

* D410: missing blank line after section

* D200: docstring should fit on one line

* D202: No blank lines allowed after function docstring

* D413: missing blank line after last section

* D212: Multi-line docstring sohuld start at the first line

* D204: blank line after class docstring

* D412: No blank lines allowed between a section header and its content

* D411: blank line before section

* D208: docstring over-indented

* D300: use triple quotes

* Backslashes

* D209: closing quotes on separate line

* D403: capitalise

* D407: missing dashed underlines

* D409: underlines

* D210: No whitespace allowed surrounding docstring text

* Enable subset of pydocstyle rules

* Include D417 as aspiration

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Minor fixups

* Ignore pydocstyle in tests

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

notebooks/image_examples/image_captioning/Image Captioning using Azure Cognitive Services.ipynb

@@ -86,8 +86,7 @@
    "outputs": [],
    "source": [
     "def get_caption(path_to_image):\n",
-    "    \"\"\"\n",
-    "    Function to get image caption when path to image file is given.\n",
+    "    \"\"\"Function to get image caption when path to image file is given.\n",
     "    Note: API_KEY and ANALYZE_URL need to be defined before calling this function.\n",
     "\n",
     "    Parameters\n",
@@ -97,8 +96,8 @@
     "    Output\n",
     "    -------\n",
     "    image caption\n",
-    "    \"\"\"\n",
     "\n",
+    "    \"\"\"\n",
     "    headers = {\n",
     "        \"Ocp-Apim-Subscription-Key\": API_KEY,\n",
     "        \"Content-Type\": \"application/octet-stream\",\n",
@@ -314,8 +313,7 @@
     "    show_grid_plot=False,\n",
     "    limit_grid=20,\n",
     "):\n",
-    "    \"\"\"\n",
-    "    Function to take a list of images and parameters such max evals etc. and return shap explanations (shap_values) for test images(X).\n",
+    "    \"\"\"Function to take a list of images and parameters such max evals etc. and return shap explanations (shap_values) for test images(X).\n",
     "    Paramaters\n",
     "    ----------\n",
     "    X               : list of images which need to be explained\n",
@@ -329,7 +327,6 @@
     "    ------\n",
     "    shap_values_list: list of shap_values objects generated for the images\n",
     "    \"\"\"\n",
-    "\n",
     "    global image_counter\n",
     "    global mask_counter\n",
     "    shap_values_list = []\n",

notebooks/image_examples/image_captioning/Image Captioning using Open Source.ipynb

@@ -154,24 +154,23 @@
    "outputs": [],
    "source": [
     "class ImageCaptioningPyTorchModel:\n",
-    "    \"\"\"\n",
-    "    Wrapper class to get image captions using Resnet model from setup above.\n",
+    "    \"\"\"Wrapper class to get image captions using Resnet model from setup above.\n",
     "    Note: This class is being used instead of tools/eval.py to get predictions (captions).\n",
     "    To get more context for this class, please refer to tools/eval.py file.\n",
     "    \"\"\"\n",
     "\n",
     "    def __init__(self, model_path, infos_path, cnn_model=\"resnet101\", device=\"cuda\"):\n",
-    "        \"\"\"\n",
-    "        Initializing the class by loading torch model and vocabulary at path given and using Resnet weights stored in data/imagenet_weights.\n",
+    "        \"\"\"Initializing the class by loading torch model and vocabulary at path given and using Resnet weights stored in data/imagenet_weights.\n",
     "        This is done to speeden the process of getting image captions and avoid loading the model every time captions are needed.\n",
+    "\n",
     "        Parameters\n",
     "        ----------\n",
     "        model_path  : pre-trained model path\n",
     "        infos_path  : pre-trained infos (vocab) path\n",
     "        cnn_model   : resnet model weights to use; options: \"resnet101\" (default), \"resnet152\"\n",
     "        device      : \"cpu\" or \"cuda\" (default)\n",
-    "        \"\"\"\n",
     "\n",
+    "        \"\"\"\n",
     "        # load infos\n",
     "        with open(infos_path, \"rb\") as f:\n",
     "            infos = utils.pickle_load(f)\n",
@@ -201,17 +200,17 @@
     "        gc.collect()\n",
     "\n",
     "    def __call__(self, image_folder, batch_size):\n",
-    "        \"\"\"\n",
-    "        Function to get captions for images placed in image_folder.\n",
+    "        \"\"\"Function to get captions for images placed in image_folder.\n",
+    "\n",
     "        Parameters\n",
     "        ----------\n",
     "        image_folder: folder of images for which captions are needed\n",
     "        batch_size  : number of images to be evaluated at once\n",
     "        Output\n",
     "        -------\n",
     "        captions    : list of captions for images in image_folder (will return a string if there is only one image in folder)\n",
-    "        \"\"\"\n",
     "\n",
+    "        \"\"\"\n",
     "        # setting eval options\n",
     "        opt = self.opt\n",
     "        opt.batch_size = batch_size\n",
@@ -414,8 +413,7 @@
     "def run_masker(\n",
     "    X, mask_value=\"inpaint_ns\", max_evals=300, batch_size=50, fixed_context=None\n",
     "):\n",
-    "    \"\"\"\n",
-    "    Function to take a list of images and parameters such max evals etc. and return shap explanations (shap_values) for test images(X).\n",
+    "    \"\"\"Function to take a list of images and parameters such max evals etc. and return shap explanations (shap_values) for test images(X).\n",
     "    Paramaters\n",
     "    ----------\n",
     "    X               : list of images which need to be explained\n",

pyproject.toml

@@ -136,16 +136,29 @@ select = [
   "UP",  # pyupgrade
   "E",  # pycodestyle
   "W",  # warning
+  "D",  # pydocstyle
+  # D417  # undocumented parameter. FIXME: get this passing
 ]
 ignore = [
   # Recommended rules to disable when using ruff formatter:
   "E117",  # Over-indented
   "E501",  # Line too long
+
+  # pydocstyle issues not yet fixed
+  "D100",  # Missing docstring in public module
+  "D101",  # Missing docstring in public class
+  "D102",  # Missing docstring in public method
+  "D103",  # Missing docstring in public function
+  "D104",  # Missing docstring in public package
+  "D105",  # Missing docstring in magic method
+  "D205",  # 1 blank line required between summary line and description
+  "D400",  # First line should end with a period
+  "D401",  # First line of docstring should be in imperative mood: "A basic partial dependence plot function."
+  "D404",  # First word of the docstring should not be "This"
 ]
 
-[tool.ruff.format]
-# For now, only Jupyter notebooks are autoformatted.
-exclude = ["**.py"]
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
 
 [tool.ruff.lint.per-file-ignores]
 # Don't apply linting/formatting to vendored code
@@ -159,7 +172,14 @@ exclude = ["**.py"]
 "notebooks/tabular_examples/tree_based_models/tree_shap_paper/*"  = ["ALL"]
 
 # Disable some unwanted rules on Jupyter notebooks
-"*.ipynb" = ["E703", "E402"]  # Allow trailing semicolons, allow imports not at top
+"*.ipynb" = ["D", "E703", "E402"]  # Allow trailing semicolons, allow imports not at top
+
+# Ignore pycodestyle in tests
+"tests/*py" = ["D"]
+
+[tool.ruff.format]
+# For now, only Jupyter notebooks are autoformatted.
+exclude = ["**.py"]
 
 [tool.coverage.run]
 source_pkgs = ["shap"]

setup.py

@@ -135,8 +135,7 @@ def run_setup(*, with_binary, with_cuda):
 
 
 def try_run_setup(*, with_binary, with_cuda):
-    """ Fails gracefully when various install steps don't work.
-    """
+    """Fails gracefully when various install steps don't work."""
     global _BUILD_ATTEMPTS
     _BUILD_ATTEMPTS += 1