Add pydocstyle to PR checks (#34)

* Add pydocstyle to requirements-dev.txt

* Move pydocstyle config to pyproject.toml

* Ignore missing docstrings for main functions

* Add pydocstyle to CI workflow

.github/workflows/ci.yml

@@ -27,3 +27,5 @@ jobs:
           pip install -r requirements-dev.txt
       - name: Check formatting
         run: black --check .
+      - name: Check docstrings
+        run: pydocstyle

.pre-commit-config.yaml

@@ -7,13 +7,12 @@ repos:
       - id: end-of-file-fixer
       - id: trailing-whitespace
   - repo: https://github.com/psf/black
-    rev: 19.10b0
+    rev: 19.10b0 # This should be kept in sync with the version in requirements-dev.in
     hooks:
       - id: black
         language_version: python3
   - repo: https://github.com/pycqa/pydocstyle
-    rev: 6.0.0
+    rev: 6.1.1 # This should be kept in sync with the version in requirements-dev.in
     hooks:
       - id: pydocstyle
-        args:
-        - --ignore=D100,D103,D212
+        additional_dependencies: ["toml"]

gnomad_mitochondria/mutserve_batch/mutserv_batch.py

@@ -13,7 +13,7 @@
 )
 
 
-def main():
+def main():  # noqa: D103
     p = init_arg_parser()
     p.add_argument(
         "--infile", required=True, help="Tab delimited file of participant and bam_path"

gnomad_mitochondria/mutserve_batch/process_mutserv.py

@@ -291,7 +291,7 @@ def initiate_deletion(
                 break
 
 
-def main(args):
+def main(args):  # noqa: D103
     input_file = args.input_file
     output_file = args.output_file
     mt_reference = args.mt_reference

gnomad_mitochondria/pipeline/add_annotations.py

@@ -1890,7 +1890,7 @@ def format_vcf(
     return input_mt, meta_dict, vcf_header_file
 
 
-def main(args):
+def main(args):  # noqa: D103
     mt_path = args.mt_path
     output_dir = args.output_dir
     participant_data = args.participant_data

gnomad_mitochondria/pipeline/annotate_coverage.py

@@ -86,7 +86,7 @@ def multi_way_union_mts(mts: list, temp_dir: str, chunk_size: int) -> hl.MatrixT
     )
 
 
-def main(args):
+def main(args):  # noqa: D103
     input_tsv = args.input_tsv
     output_ht = args.output_ht
     temp_dir = args.temp_dir

gnomad_mitochondria/pipeline/combine_vcfs.py

@@ -335,7 +335,7 @@ def apply_mito_artifact_filter(
     return mt
 
 
-def main(args):
+def main(args):  # noqa: D103
     participant_data = args.participant_data
     coverage_mt_path = args.coverage_mt_path
     vcf_col_name = args.vcf_col_name

gnomad_mitochondria/pipeline/subset_cov_to_release.py

@@ -16,7 +16,7 @@
 logger.setLevel(logging.INFO)
 
 
-def main(args):
+def main(args):  # noqa: D103
     input_mt_path = args.input_mt_path
     cov_mt_path = args.cov_mt_path
     out_tsv_path = args.out_tsv_path

gnomad_mitochondria/utils/reformat_mitotip.py

@@ -4,7 +4,7 @@
 from subprocess import check_output
 
 
-def main(args):
+def main(args):  # noqa: D103
     mitotip_scores = args.mitotip_scores
     mt_reference = args.mt_reference
     output_file = args.output_file

pyproject.toml

@@ -0,0 +1,7 @@
+[tool.pydocstyle]
+convention = "pep257"
+match = ".*\\.py"
+add_ignore = [
+  "D100", # Do not require docstrings for modules.
+  "D104", # Do not require docstrings for packages (in __init__.py).
+]

requirements-dev.in

@@ -1,2 +1,3 @@
-black==19.10b0
+black==19.10b0 # This should be kept in sync with the version in .pre-commit-config.yaml
 pip-tools
+pydocstyle[toml]==6.1.1 # This should be kept in sync with the version in .pre-commit-config.yaml

requirements-dev.txt

@@ -14,30 +14,24 @@ click==8.0.1
     # via
     #   black
     #   pip-tools
-importlib-metadata==4.5.0
-    # via
-    #   click
-    #   pep517
 pathspec==0.8.1
     # via black
 pep517==0.10.0
     # via pip-tools
 pip-tools==6.1.0
     # via -r requirements-dev.in
+pydocstyle[toml]==6.1.1
+    # via -r requirements-dev.in
 regex==2021.4.4
     # via black
+snowballstemmer==2.1.0
+    # via pydocstyle
 toml==0.10.2
     # via
     #   black
-    #   pep517
+    #   pydocstyle
 typed-ast==1.4.3
     # via black
-typing-extensions==3.10.0.0
-    # via importlib-metadata
-zipp==3.4.1
-    # via
-    #   importlib-metadata
-    #   pep517
 
 # The following packages are considered to be unsafe in a requirements file:
 # pip