Add doc formatting to circleci. (facebookresearch#2124)

* Add doc formatting to circleci.

* Try again.

* Debugging messages.

* Drop a few unnecessary requirements; improve output.

* Sigh, bug fixes.

* Update contributing.

* Update circleci config.

* More explicit.

* Comments, minor changes.

* Slightly nicer output.

* comment change.

* Whoops, dropped a dep.

* Auto-format docstrings. (facebookresearch#2182)

* Autoformat.

* Ugh.

.circleci/config.yml

@@ -281,12 +281,30 @@ jobs:
           name: minimum black dependencies
           working_directory: ~/ParlAI
           command: |
-            pip install -q gitpython black  # only what's needd to lint
+            pip install -q gitpython black  # only what's needed to lint
       - run:
           name: black
           working_directory: ~/ParlAI
           command: |
-            bash ./tests/lint_changed.sh -b
+            bash ./autoformat.sh -b -c
+
+  docformat:
+    <<: *standard_cpu36
+    working_directory: ~/ParlAI
+    steps:
+      - checkout
+      - <<: *fixgit
+      - <<: *setup
+      - run:
+          name: minimum docformat dependencies
+          working_directory: ~/ParlAI
+          command: |
+            pip install -q gitpython docformatter  # only what's needed to lint
+      - run:
+          name: docformat
+          working_directory: ~/ParlAI
+          command: |
+            bash ./autoformat.sh -d -c
 
   lint:
     <<: *standard_cpu37
@@ -305,12 +323,12 @@ jobs:
           name: minimum lint dependencies
           working_directory: ~/ParlAI
           command: |
-            pip install -q flake8 gitpython flake8-bugbear  # only what's needd to lint
+            pip install -q flake8 gitpython flake8-bugbear  # only what's needed to lint
       - run:
           name: Lint
           working_directory: ~/ParlAI
           command: |
-            bash ./tests/lint_changed.sh
+            bash ./autoformat.sh -c -f
 
   nightly_gpu_tests:
     <<: *gpu
@@ -484,6 +502,7 @@ workflows:
     jobs:
       - black
       - lint
+      - docformat
       - unittests_gpu11
       - unittests_gpu12
       - unittests_37

.circleci/triggers.py

@@ -20,12 +20,16 @@
 
 
 def detect_all():
-    """Check if we should run all tests."""
+    """
+    Check if we should run all tests.
+    """
     return any(kw in testing_utils.git_commit_messages() for kw in ['[all]', '[long]'])
 
 
 def detect_gpu():
-    """Check if we should run GPU tests."""
+    """
+    Check if we should run GPU tests.
+    """
     commit_msg = '[gpu]' in testing_utils.git_commit_messages()
     test_changed = any(
         'tests/nightly/gpu' in fn for fn in testing_utils.git_changed_files()
@@ -34,7 +38,9 @@ def detect_gpu():
 
 
 def detect_data():
-    """Check if we should run data tests."""
+    """
+    Check if we should run data tests.
+    """
     commit_msg = '[data]' in testing_utils.git_commit_messages().lower()
     test_changed = any(
         testing_utils.is_new_task_filename(fn)
@@ -44,7 +50,9 @@ def detect_data():
 
 
 def detect_mturk():
-    """Check if we should run mturk tests."""
+    """
+    Check if we should run mturk tests.
+    """
     commit_msg = '[mturk]' in testing_utils.git_commit_messages().lower()
     mturk_changed = any(
         'parlai/mturk' in fn for fn in testing_utils.git_changed_files()
@@ -60,7 +68,9 @@ def detect_mturk():
 
 
 def main():
-    """Run the program, printing the name of tests we should run to stdout."""
+    """
+    Run the program, printing the name of tests we should run to stdout.
+    """
     run_all = detect_all()
     for testname, detector in MAPPING.items():
         if run_all or detector():

.flake8

@@ -9,7 +9,6 @@ extend-ignore =
     E266
     W503
     F403
-    D202
-select = C,E,F,W,B,B950,D,RST
+select = C,E,F,W,B,B950,RST
 
 max-line-length=80

CONTRIBUTING.md

@@ -11,7 +11,7 @@ We actively welcome your pull requests.
    and run `pre-commit install` once.
 2. If you've added code that should be tested, add tests.
 3. If you've changed APIs, update the documentation.
-4. Black your code (`black`), and make sure your code lints (`bash tests/lint_changed.sh`).
+4. Autoformat and lint your code (`bash autoformat.sh`)
 5. Ensure the test suite passes. Run `python setup.py test`.
 6. If you've added a new dataset, you should also run
    `python setup.py test -s tests.suites.datatests`. Copy-paste the output into a

autoformat.sh

@@ -0,0 +1,174 @@
+#!/bin/bash
+
+# Copyright (c) Facebook, Inc. and its affiliates.
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+# exit on errors
+set -e
+
+# configuration options for our doc formatting
+DOCOPTS="--pre-summary-newline --wrap-descriptions 88 --wrap-summaries 88 \
+    --make-summary-multi-line"
+
+usage () {
+    # prints the help message
+    cat <<EOF
+Usage: $0
+
+Autoformats (or checks) code so it conforms with ParlAI standards. By default,
+runs black, flake8, and docformatter only on the changed files in the current branch.
+
+Optional Arguments
+
+  -a, --all          run on all files, not just changed ones.
+  -b, --black        only run black.
+  -c, --check        perform a check, but don't make any changes.
+  -d, --doc          only run docformatter.
+  -f, --flake8       only run flake8.
+  -h, --help         print this help message and exit
+  -i, --internal     run within parlai_internal
+EOF
+}
+
+reroot() {
+    # possibly rewrite all filenames if root is nonempty
+    if [[ "$1" != "" ]]; then
+        cat | xargs -I '{}' realpath --relative-to=. $1/'{}'
+    else
+        cat
+    fi
+}
+
+onlyexists() {
+    # filter filenames based on what exists on disk
+    while read fn; do
+        if [ -f "${fn}" ]; then
+            echo "$fn"
+        fi
+    done
+}
+
+# parse the command line args
+RUN_ALL_FILES=0
+RUNALL=1
+INTERNAL=0
+CHECK=0
+CMD=""
+while true; do
+  case $1 in
+    -h | --help)
+      usage
+      exit 0
+      ;;
+    -a | --all)
+      RUN_ALL_FILES=1
+      ;;
+    -f | --flake8)
+      [[ "$CMD" != "" ]] && (echo "Don't mix args." && false);
+      RUNALL=0
+      CMD="flake8"
+      ;;
+    -c | --check)
+      CHECK=1
+      ;;
+    -d | --doc)
+      [[ "$CMD" != "" ]] && (echo "Don't mix args." && false);
+      CMD="docformatter"
+      RUNALL=0
+      ;;
+    -i | --internal)
+      INTERNAL=1
+      ;;
+    -b | --black)
+      [[ "$CMD" != "" ]] && (echo "Don't mix args." && false);
+      CMD="black"
+      RUNALL=0
+      ;;
+    "")
+      break
+      ;;
+    *)
+      usage
+      echo
+      echo "Cannot handle arg $1."
+      exit 1
+      ;;
+  esac
+  shift
+done
+
+
+# decide which repo we're working on
+if [[ $INTERNAL -eq 1 ]]; then
+    ROOT="$(git -C ./parlai_internal/ rev-parse --show-toplevel)"
+    REPO="-C ./parlai_internal"
+else
+    ROOT=""
+    REPO=""
+fi
+
+# find out what files we're working on
+if [[ $RUN_ALL_FILES -eq 1 ]]; then
+    CHECK_FILES="$(git $REPO ls-files | grep '\.py$' | reroot $ROOT | onlyexists $ROOT | tr '\n' ' ')"
+else
+    CHECK_FILES="$(git $REPO diff --name-only master... | grep '\.py$' | reroot $ROOT | onlyexists | tr '\n' ' ')"
+fi
+
+# if we're doing all the tests, we should run them in serial
+if [[ $RUNALL -eq 1 ]]
+then
+    if [[ $CHECK -eq 1 ]]; then A="$A --check"; fi
+    if [[ $INTERNAL -eq 1 ]]; then A="$A --internal"; fi
+    if [[ $RUN_ALL_FILES -eq 1 ]]; then A="$A --all"; fi
+    bash $0 --black $A
+    bash $0 --doc $A
+    bash $0 --flake8 $A
+    exit 0
+fi
+
+# finally do the actual checks
+if [ "$CHECK_FILES" != "" ]
+then
+    if [[ "$CMD" == "black" ]]
+    then
+        command -v black >/dev/null || \
+            ( echo "Please run \`pip install black\` and rerun $0." && false )
+        if [[ $CHECK -eq 0 ]]
+        then
+            black $CHECK_FILES
+        else
+            if ! ( black --check $CHECK_FILES 2>/dev/null ); then
+                echo -e "\033[0;31mSome files need to be blacked.\033[0m"
+                echo "Please run \`bash ./autoformat.sh\` and commit the changes."
+                exit 1
+            fi
+        fi
+    elif [[ "$CMD" == "docformatter" ]]
+    then
+        command -v docformatter > /dev/null || \
+            ( echo "Please run \`pip install docformatter\` and rerun $0." && false )
+        if [[ $CHECK -eq 0 ]]
+        then
+            docformatter -i $DOCOPTS $CHECK_FILES
+        else
+            if ! docformatter -c $DOCOPTS $CHECK_FILES > /dev/null 2>&1; then
+                echo -e "\033[0;31mSome docstrings need to be formatted.\033[0m"
+                echo "Please run \`./autoformat.sh\` and commit the changes."
+                exit 1
+            fi
+        fi
+    elif [[ "$CMD" == "flake8" ]]
+    then
+        command -v flake8 >/dev/null || \
+            ( echo "Please run \`pip install flake8\` and rerun $0." && false )
+
+        # soft complaint on too-long-lines
+        flake8 --select=E501 --show-source $CHECK_FILES
+        # hard complaint on really long lines
+        flake8 --max-line-length=127 --show-source $CHECK_FILES
+    else
+        echo "Don't know how to \`$CMD\`."
+        exit 1
+    fi
+fi

examples/base_train.py

@@ -3,9 +3,9 @@
 # Copyright (c) Facebook, Inc. and its affiliates.
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
-"""Basic template of training loop.
-We create an agent that will train on the training task, and be evaluated
-on the validation version of the task.
+"""
+Basic template of training loop. We create an agent that will train on the training
+task, and be evaluated on the validation version of the task.
 
 We then do one iteration over ten training examples and one validation example,
 printing reports from those tasks after completing those iterations.

examples/build_pytorch_data.py

@@ -3,8 +3,8 @@
 # Copyright (c) Facebook, Inc. and its affiliates.
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
-"""Generates a pytorch data file from the training data; for use in the
-PytorchDataTeacher.
+"""
+Generates a pytorch data file from the training data; for use in the PytorchDataTeacher.
 
 For more documentation, see parlai.scripts.build_pytorch_data.
 """

examples/display_data.py

@@ -3,8 +3,9 @@
 # Copyright (c) Facebook, Inc. and its affiliates.
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
-"""Basic example which iterates through the tasks specified and prints them out.
-Used for verification of data loading and iteration.
+"""
+Basic example which iterates through the tasks specified and prints them out. Used for
+verification of data loading and iteration.
 
 For more documentation, see parlai.scripts.display_data.
 """

examples/eval_model.py

@@ -3,8 +3,9 @@
 # Copyright (c) Facebook, Inc. and its affiliates.
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
-"""Basic example which iterates through the tasks specified and
-evaluates the given model on them.
+"""
+Basic example which iterates through the tasks specified and evaluates the given model
+on them.
 
 For more documentation, see parlai.scripts.eval_model.
 """

examples/extract_image_feature.py

@@ -4,8 +4,9 @@
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
 
-"""Basic example which iterates through the tasks specified and load/extract
-the image features.
+"""
+Basic example which iterates through the tasks specified and load/extract the image
+features.
 
 For more documentation, use parlai.scripts.extract_image_feature.
 """

examples/interactive.py

@@ -3,7 +3,8 @@
 # Copyright (c) Facebook, Inc. and its affiliates.
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
-"""Basic example which allows local human keyboard input to talk to a trained model.
+"""
+Basic example which allows local human keyboard input to talk to a trained model.
 
 For documentation, see parlai.scripts.interactive.
 """

examples/profile_train.py

@@ -3,7 +3,8 @@
 # Copyright (c) Facebook, Inc. and its affiliates.
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
-"""Run the python or pytorch profiler and prints the results.
+"""
+Run the python or pytorch profiler and prints the results.
 
 For documentation, see parlai.scripts.profile_train.
 """

examples/remote.py

@@ -4,8 +4,9 @@
 # This source code is licensed under the MIT license found in the
 # LICENSE file in the root directory of this source tree.
 
-"""Simple loop which sets up a remote connection. The paired agent can run this
-same loop but with the '--remote-host' flag set. For example...
+"""
+Simple loop which sets up a remote connection. The paired agent can run this same loop
+but with the '--remote-host' flag set. For example...
 
 Agent 1:
 python remote.py