DOC Document undocumented parameters and add CI check(#1248)

Author: NicolasHug

.circleci/config.yml

@@ -577,6 +577,18 @@ jobs:
             target=${tag:-master}
             ~/workspace/.circleci/build_docs/commit_docs.sh ~/workspace $target
 
+  docstring_parameters_sync:
+    <<: *binary_common
+    docker:
+      - image: circleci/python:3.8
+    steps:
+      - checkout
+      - run:
+          name: Check parameters docstring sync
+          command: |
+            pip install --user pydocstyle
+            pydocstyle torchaudio
+
 workflows:
   build:
     jobs:
@@ -678,6 +690,11 @@ workflows:
           python_version: '3.8'
           requires:
           - build_docs
+      - docstring_parameters_sync:
+          name: docstring_parameters_sync
+          python_version: '3.8'
+          requires:
+          - binary_linux_wheel_py3.8
   unittest:
     jobs:
       - download_third_parties_nix:

.circleci/config.yml.in

@@ -577,6 +577,18 @@ jobs:
             target=${tag:-master}
             ~/workspace/.circleci/build_docs/commit_docs.sh ~/workspace $target
 
+  docstring_parameters_sync:
+    <<: *binary_common
+    docker:
+      - image: circleci/python:3.8
+    steps:
+      - checkout
+      - run:
+          name: Check parameters docstring sync
+          command: |
+            pip install --user pydocstyle
+            pydocstyle torchaudio
+
 workflows:
   build:
     jobs:

.circleci/regenerate.py

@@ -36,6 +36,8 @@ def build_workflows(prefix='', upload=False, filter_branch=None, indentation=6):
         # Build on every pull request, but upload only on nightly and tags
         w += build_doc_job(None)
         w += upload_doc_job('nightly')
+        w += docstring_parameters_sync_job(None)
+
 
     return indent(indentation, w)
 
@@ -100,6 +102,18 @@ def upload_doc_job(filter_branch):
     return [{"upload_docs": job}]
 
 
+def docstring_parameters_sync_job(filter_branch):
+    job = {
+        "name": "docstring_parameters_sync",
+        "python_version": "3.8",
+        "requires": ["binary_linux_wheel_py3.8", ],
+    }
+
+    if filter_branch:
+        job["filters"] = gen_filter_branch_tree(filter_branch)
+    return [{"docstring_parameters_sync": job}]
+
+
 def generate_base_workflow(base_workflow_name, python_version, filter_branch, os_type, btype):
 
     d = {

examples/source_separation/utils/dataset/wsj0mix.py

@@ -63,7 +63,7 @@ def __len__(self) -> int:
     def __getitem__(self, key: int) -> SampleType:
         """Load the n-th sample from the dataset.
         Args:
-            n (int): The index of the sample to be loaded
+            key (int): The index of the sample to be loaded
         Returns:
             tuple: ``(sample_rate, mix_waveform, list_of_source_waveforms)``
         """

setup.cfg

@@ -0,0 +1,2 @@
+[pydocstyle]
+select = D417 # Missing argument descriptions in the docstring 

test/torchaudio_unittest/common_utils/kaldi_utils.py

@@ -18,11 +18,10 @@ def run_kaldi(command, input_type, input_value):
     """Run provided Kaldi command, pass a tensor and get the resulting tensor
 
     Args:
-        input_type: str
-            'ark' or 'scp'
-        input_value:
-            Tensor for 'ark'
-            string for 'scp' (path to an audio file)
+        command (list of str): The command with arguments
+        input_type (str): 'ark' or 'scp'
+        input_value (Tensor for 'ark', string for 'scp'): The input to pass.
+            Must be a path to an audio file for 'scp'.
     """
     import kaldi_io
 

torchaudio/_internal/module_utils.py

@@ -41,7 +41,8 @@ def deprecated(direction: str, version: Optional[str] = None):
     """Decorator to add deprecation message
 
     Args:
-        direction: Migration steps to be given to users.
+        direction (str): Migration steps to be given to users.
+        version (str or int): The version when the object will be removed
     """
     def decorator(func):
 

torchaudio/backend/_soundfile_backend.py

@@ -240,15 +240,14 @@ def save(
             This functionalso handles ``pathlib.Path`` objects, but is annotated as ``str``
             for the consistency with "sox_io" backend, which has a restriction on type annotation
             for TorchScript compiler compatiblity.
-        tensor (torch.Tensor): Audio data to save. must be 2D tensor.
+        src (torch.Tensor): Audio data to save. must be 2D tensor.
         sample_rate (int): sampling rate
-        channels_first (bool):
-            If ``True``, the given tensor is interpreted as ``[channel, time]``,
+        channels_first (bool): If ``True``, the given tensor is interpreted as ``[channel, time]``,
             otherwise ``[time, channel]``.
-        compression (Optional[float]):
-            Not used. It is here only for interface compatibility reson with "sox_io" backend.
-        format (str, optional):
-            Output audio format. This is required when the output audio format cannot be infered from
+        compression (Optional[float]): Not used.
+            It is here only for interface compatibility reson with "sox_io" backend.
+        format (str, optional): Output audio format.
+            This is required when the output audio format cannot be infered from
             ``filepath``, (such as file extension or ``name`` attribute of the given file object).
     """
     if src.ndim != 2:

torchaudio/backend/sox_io_backend.py

@@ -205,16 +205,15 @@ def save(
         and corresponding codec libraries such as ``libmad`` or ``libmp3lame`` etc.
 
     Args:
-        filepath (str or pathlib.Path):
-            Path to save file. This function also handles ``pathlib.Path`` objects, but is annotated
+        filepath (str or pathlib.Path): Path to save file.
+            This function also handles ``pathlib.Path`` objects, but is annotated
             as ``str`` for TorchScript compiler compatibility.
-        tensor (torch.Tensor): Audio data to save. must be 2D tensor.
+        src (torch.Tensor): Audio data to save. must be 2D tensor.
         sample_rate (int): sampling rate
-        channels_first (bool):
-            If ``True``, the given tensor is interpreted as ``[channel, time]``,
+        channels_first (bool): If ``True``, the given tensor is interpreted as ``[channel, time]``,
             otherwise ``[time, channel]``.
-        compression (Optional[float]):
-            Used for formats other than WAV. This corresponds to ``-C`` option of ``sox`` command.
+        compression (Optional[float]): Used for formats other than WAV.
+            This corresponds to ``-C`` option of ``sox`` command.
 
                 * | ``MP3``: Either bitrate (in ``kbps``) with quality factor, such as ``128.2``, or
                   | VBR encoding with quality factor such as ``-4.2``. Default: ``-4.5``.
@@ -224,11 +223,10 @@ def save(
                   | and lowest quality. Default: ``3``.
 
             See the detail at http://sox.sourceforge.net/soxformat.html.
-        format (str, optional):
-            Output audio format. This is required when the output audio format cannot be infered from
+        format (str, optional): Output audio format.
+            This is required when the output audio format cannot be infered from
             ``filepath``, (such as file extension or ``name`` attribute of the given file object).
-        dtype (str, optional)
-            Output tensor dtype.
+        dtype (str, optional): Output tensor dtype.
             Valid values: ``"uint8", "int16", "int32", "float32", "float64", None``
             ``dtype=None`` means no conversion is performed.
             ``dtype`` parameter is only effective for ``float32`` Tensor.

torchaudio/functional/filtering.py

@@ -446,7 +446,7 @@ def _apply_probability_distribution(
     or Gaussian curve, typical of dither generated by analog sources.
     Args:
         waveform (Tensor): Tensor of audio of dimension (..., time)
-        probability_density_function (str, optional): The density function of a
+        density_function (str, optional): The density function of a
            continuous random variable (Default: ``"TPDF"``)
            Options: Triangular Probability Density Function - `TPDF`
                     Rectangular Probability Density Function - `RPDF`