Repository: pytorch/ignite

Issue:
Use autodoc_typehints = "description" in conf.py
## 📚 Documentation

EDITED HERE: As a help wanted issue, please, see below comment https://github.com/pytorch/ignite/issues/1665#issuecomment-783240506 on what remains to do here. Thanks 


If there are many arguments in class/function/method, it's a little hard to read/scan all arguments (due to typehints).
Although there is a `Parameters` section, there might be missing some arguments (rarely though).
And we are duplicating type hints work in both signatures and docstring. Writing once can make less work on authors and less type hints mismatch can occur.

If we can remove type hints, it can be a little easier to read, and showing type hints only in `Parameters` section.

For example:
Before:
![Screen Shot 2021-02-21 at 22 52 16](https://user-images.githubusercontent.com/32727188/108631357-ff79fb00-7497-11eb-9409-79f9c7f12424.png)
After:
![Screen Shot 2021-02-21 at 22 51 40](https://user-images.githubusercontent.com/32727188/108631370-11f43480-7498-11eb-935f-c3fd5f69371f.png)

Changing to this docs style needs a little work. It needs to 
- add
```py
autoclass_content = "both"
autodoc_typehints = "description"  # new in sphinx 3.1
```
those lines in `conf.py`
- removing type hints in docstring
- leaving type hints only in signatures.

Let me know what you think.
cc: @vfdev-5 @sdesrozis @trsvchn 


Discussion:
@ydcjeff thanks! Yes, it would be a nice improvement of the docs ! I also found that function's signature is cluttered by type hints which can hard to read. Let's introduce those configs to `conf.py`
@ydcjeff Yes, I like it! BTW, I didn't know that we can do that so easily, I was expecting to use https://github.com/agronholm/sphinx-autodoc-typehints as a new dependency for that.
@vfdev-5 I will send PR tmr

@trsvchn yes, that `description` option is new in sphinx 3.1 so that we can do that
@ydcjeff typehints have to be removed from docstring, haven't they ? If so, It seems to be a huge work that we could scatter between us. 
> @ydcjeff typehints have to be removed from docstring, haven't they ?

@sdesrozis why ? 

As far as I understand, it is just about adding to additional lines to `conf.py`.
Yes, @sdesrozis is correct. We only need to add type hints in signatures, we can remove the type hints added manually in docstring. Sorry not mentioning clearly.

For the attached example, docstring is just:
```rst
to_save: Dictionary with the objects to save. Objects should have implemented ``state_dict`` and
        ``load_state_dict`` methods. If contains objects of type torch `DistributedDataParallel`_ or
        `DataParallel`_, their internal wrapped model is automatically saved (to avoid additional key ``module.`` in
        the state dictionary).
save_handler: Method or callable class to
        use to save engine and other provided objects. Function receives two objects: checkpoint as a dictionary
        and filename. If ``save_handler`` is callable class, it can
        inherit of :class:`~ignite.handlers.checkpoint.BaseSaveHandler` and optionally implement ``remove`` method
        to keep a fixed number of saved checkpoints. In case if user needs to save engine's checkpoint on a disk,
        ``save_handler`` can be defined with :class:`~ignite.handlers.DiskSaver`.
```

Since the docs started with sphinx 2.x, we also need to add type hints in docstring to appear in the description.
But, sphinx 3.x has this option, we would need a migration on that.
And I am willing to take, but as @sdesrozis said, this can be out of sync with current ongoing (feature) PRs.
I will find other solutions in the mean time.
Oh, I see, thanks for the clarification @ydcjeff ! 
I think we can proceed with that in parallel with other PRs and sync between them depending on which one is merged before.


Resolving patch:
diff --git a/docs/source/conf.py b/docs/source/conf.py
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -51,6 +51,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.doctest",
     "sphinx.ext.intersphinx",
@@ -205,7 +206,8 @@
 
 # -- Type hints configs ------------------------------------------------------
 
-autodoc_typehints = "signature"
+autoclass_content = "both"
+autodoc_typehints = "description"
 
 # -- A patch that turns-off cross refs for type annotations ------------------
 
diff --git a/ignite/contrib/engines/common.py b/ignite/contrib/engines/common.py
--- a/ignite/contrib/engines/common.py
+++ b/ignite/contrib/engines/common.py
@@ -59,35 +59,35 @@ def setup_common_training_handlers(
         - Two progress bars on epochs and optionally on iterations
 
     Args:
-        trainer (Engine): trainer engine. Output of trainer's `update_function` should be a dictionary
+        trainer: trainer engine. Output of trainer's `update_function` should be a dictionary
             or sequence or a single tensor.
-        train_sampler (torch.utils.data.DistributedSampler, optional): Optional distributed sampler used to call
+        train_sampler: Optional distributed sampler used to call
             `set_epoch` method on epoch started event.
-        to_save (dict, optional): dictionary with objects to save in the checkpoint. This argument is passed to
+        to_save: dictionary with objects to save in the checkpoint. This argument is passed to
             :class:`~ignite.handlers.Checkpoint` instance.
-        save_every_iters (int, optional): saving interval. By default, `to_save` objects are stored
+        save_every_iters: saving interval. By default, `to_save` objects are stored
             each 1000 iterations.
-        output_path (str, optional): output path to indicate where `to_save` objects are stored. Argument is mutually
+        output_path: output path to indicate where `to_save` objects are stored. Argument is mutually
             exclusive with ``save_handler``.
-        lr_scheduler (ParamScheduler or subclass of `torch.optim.lr_scheduler._LRScheduler`): learning rate scheduler
+        lr_scheduler: learning rate scheduler
             as native torch LRScheduler or ignite's parameter scheduler.
-        with_gpu_stats (bool, optional): if True, :class:`~ignite.contrib.metrics.handlers.GpuInfo` is attached to the
+        with_gpu_stats: if True, :class:`~ignite.contrib.metrics.GpuInfo` is attached to the
             trainer. This requires `pynvml` package to be installed.
-        output_names (list/tuple, optional): list of names associated with `update_function` output dictionary.
-        with_pbars (bool, optional): if True, two progress bars on epochs and optionally on iterations are attached.
+        output_names: list of names associated with `update_function` output dictionary.
+        with_pbars: if True, two progress bars on epochs and optionally on iterations are attached.
             Default, True.
-        with_pbar_on_iters (bool, optional): if True, a progress bar on iterations is attached to the trainer.
+        with_pbar_on_iters: if True, a progress bar on iterations is attached to the trainer.
             Default, True.
-        log_every_iters (int, optional): logging interval for :class:`~ignite.contrib.metrics.handlers.GpuInfo` and for
+        log_every_iters: logging interval for :class:`~ignite.contrib.metrics.GpuInfo` and for
             epoch-wise progress bar. Default, 100.
-        stop_on_nan (bool, optional): if True, :class:`~ignite.handlers.TerminateOnNan` handler is added to the trainer.
+        stop_on_nan: if True, :class:`~ignite.handlers.TerminateOnNan` handler is added to the trainer.
             Default, True.
-        clear_cuda_cache (bool, optional): if True, `torch.cuda.empty_cache()` is called every end of epoch.
+        clear_cuda_cache: if True, `torch.cuda.empty_cache()` is called every end of epoch.
             Default, True.
-        save_handler (callable or :class:`~ignite.handlers.checkpoint.BaseSaveHandler`, optional): Method or callable
-            class to use to store ``to_save``. See :class:`~ignite.handlers.checkpoint.Checkpoint` for more details.
+        save_handler: Method or callable
+            class to use to store ``to_save``. See :class:`~ignite.handlers.Checkpoint` for more details.
             Argument is mutually exclusive with ``output_path``.
-        **kwargs: optional keyword args to be passed to construct :class:`~ignite.handlers.checkpoint.Checkpoint`.
+        kwargs: optional keyword args to be passed to construct :class:`~ignite.handlers.Checkpoint`.
     """
 
     if idist.get_world_size() > 1:
@@ -352,15 +352,15 @@ def setup_tb_logging(
         - Evaluation metrics
 
     Args:
-        output_path (str): logging directory path
-        trainer (Engine): trainer engine
-        optimizers (torch.optim.Optimizer or dict of torch.optim.Optimizer, optional): single or dictionary of
+        output_path: logging directory path
+        trainer: trainer engine
+        optimizers: single or dictionary of
             torch optimizers. If a dictionary, keys are used as tags arguments for logging.
-        evaluators (Engine or dict of Engine, optional): single or dictionary of evaluators. If a dictionary,
+        evaluators: single or dictionary of evaluators. If a dictionary,
             keys are used as tags arguments for logging.
-        log_every_iters (int, optional): interval for loggers attached to iteration events. To log every iteration,
+        log_every_iters: interval for loggers attached to iteration events. To log every iteration,
             value can be set to 1 or None.
-        **kwargs: optional keyword args to be passed to construct the logger.
+        kwargs: optional keyword args to be passed to construct the logger.
 
     Returns:
         :class:`~ignite.contrib.handlers.tensorboard_logger.TensorboardLogger`
@@ -384,14 +384,14 @@ def setup_visdom_logging(
         - Evaluation metrics
 
     Args:
-        trainer (Engine): trainer engine
-        optimizers (torch.optim.Optimizer or dict of torch.optim.Optimizer, optional): single or dictionary of
+        trainer: trainer engine
+        optimizers: single or dictionary of
             torch optimizers. If a dictionary, keys are used as tags arguments for logging.
-        evaluators (Engine or dict of Engine, optional): single or dictionary of evaluators. If a dictionary,
+        evaluators: single or dictionary of evaluators. If a dictionary,
             keys are used as tags arguments for logging.
-        log_every_iters (int, optional): interval for loggers attached to iteration events. To log every iteration,
+        log_every_iters: interval for loggers attached to iteration events. To log every iteration,
             value can be set to 1 or None.
-        **kwargs: optional keyword args to be passed to construct the logger.
+        kwargs: optional keyword args to be passed to construct the logger.
 
     Returns:
         :class:`~ignite.contrib.handlers.visdom_logger.VisdomLogger`
@@ -415,14 +415,14 @@ def setup_mlflow_logging(
         - Evaluation metrics
 
     Args:
-        trainer (Engine): trainer engine
-        optimizers (torch.optim.Optimizer or dict of torch.optim.Optimizer, optional): single or dictionary of
+        trainer: trainer engine
+        optimizers: single or dictionary of
             torch optimizers. If a dictionary, keys are used as tags arguments for logging.
-        evaluators (Engine or dict of Engine, optional): single or dictionary of evaluators. If a dictionary,
+        evaluators: single or dictionary of evaluators. If a dictionary,
             keys are used as tags arguments for logging.
-        log_every_iters (int, optional): interval for loggers attached to iteration events. To log every iteration,
+        log_every_iters: interval for loggers attached to iteration events. To log every iteration,
             value can be set to 1 or None.
-        **kwargs: optional keyword args to be passed to construct the logger.
+        kwargs: optional keyword args to be passed to construct the logger.
 
     Returns:
         :class:`~ignite.contrib.handlers.mlflow_logger.MLflowLogger`
@@ -446,14 +446,14 @@ def setup_neptune_logging(
         - Evaluation metrics
 
     Args:
-        trainer (Engine): trainer engine
-        optimizers (torch.optim.Optimizer or dict of torch.optim.Optimizer, optional): single or dictionary of
+        trainer: trainer engine
+        optimizers: single or dictionary of
             torch optimizers. If a dictionary, keys are used as tags arguments for logging.
-        evaluators (Engine or dict of Engine, optional): single or dictionary of evaluators. If a dictionary,
+        evaluators: single or dictionary of evaluators. If a dictionary,
             keys are used as tags arguments for logging.
-        log_every_iters (int, optional): interval for loggers attached to iteration events. To log every iteration,
+        log_every_iters: interval for loggers attached to iteration events. To log every iteration,
             value can be set to 1 or None.
-        **kwargs: optional keyword args to be passed to construct the logger.
+        kwargs: optional keyword args to be passed to construct the logger.
 
     Returns:
         :class:`~ignite.contrib.handlers.neptune_logger.NeptuneLogger`
@@ -477,14 +477,14 @@ def setup_wandb_logging(
         - Evaluation metrics
 
     Args:
-        trainer (Engine): trainer engine
-        optimizers (torch.optim.Optimizer or dict of torch.optim.Optimizer, optional): single or dictionary of
+        trainer: trainer engine
+        optimizers: single or dictionary of
             torch optimizers. If a dictionary, keys are used as tags arguments for logging.
-        evaluators (Engine or dict of Engine, optional): single or dictionary of evaluators. If a dictionary,
+        evaluators: single or dictionary of evaluators. If a dictionary,
             keys are used as tags arguments for logging.
-        log_every_iters (int, optional): interval for loggers attached to iteration events. To log every iteration,
+        log_every_iters: interval for loggers attached to iteration events. To log every iteration,
             value can be set to 1 or None.
-        **kwargs: optional keyword args to be passed to construct the logger.
+        kwargs: optional keyword args to be passed to construct the logger.
 
     Returns:
         :class:`~ignite.contrib.handlers.wandb_logger.WandBLogger`
@@ -508,14 +508,14 @@ def setup_plx_logging(
         - Evaluation metrics
 
     Args:
-        trainer (Engine): trainer engine
-        optimizers (torch.optim.Optimizer or dict of torch.optim.Optimizer, optional): single or dictionary of
+        trainer: trainer engine
+        optimizers: single or dictionary of
             torch optimizers. If a dictionary, keys are used as tags arguments for logging.
-        evaluators (Engine or dict of Engine, optional): single or dictionary of evaluators. If a dictionary,
+        evaluators: single or dictionary of evaluators. If a dictionary,
             keys are used as tags arguments for logging.
-        log_every_iters (int, optional): interval for loggers attached to iteration events. To log every iteration,
+        log_every_iters: interval for loggers attached to iteration events. To log every iteration,
             value can be set to 1 or None.
-        **kwargs: optional keyword args to be passed to construct the logger.
+        kwargs: optional keyword args to be passed to construct the logger.
 
     Returns:
         :class:`~ignite.contrib.handlers.polyaxon_logger.PolyaxonLogger`
@@ -539,14 +539,14 @@ def setup_clearml_logging(
         - Evaluation metrics
 
     Args:
-        trainer (Engine): trainer engine
-        optimizers (torch.optim.Optimizer or dict of torch.optim.Optimizer, optional): single or dictionary of
+        trainer: trainer engine
+        optimizers: single or dictionary of
             torch optimizers. If a dictionary, keys are used as tags arguments for logging.
-        evaluators (Engine or dict of Engine, optional): single or dictionary of evaluators. If a dictionary,
+        evaluators: single or dictionary of evaluators. If a dictionary,
             keys are used as tags arguments for logging.
-        log_every_iters (int, optional): interval for loggers attached to iteration events. To log every iteration,
+        log_every_iters: interval for loggers attached to iteration events. To log every iteration,
             value can be set to 1 or None.
-        **kwargs: optional keyword args to be passed to construct the logger.
+        kwargs: optional keyword args to be passed to construct the logger.
 
     Returns:
         :class:`~ignite.contrib.handlers.clearml_logger.ClearMLLogger`
@@ -588,21 +588,21 @@ def gen_save_best_models_by_val_score(
     ``save_handler``.
 
     Args:
-        save_handler (callable or :class:`~ignite.handlers.checkpoint.BaseSaveHandler`): Method or callable class to
+        save_handler: Method or callable class to
             use to save engine and other provided objects. Function receives two objects: checkpoint as a dictionary
             and filename. If ``save_handler`` is callable class, it can
             inherit of :class:`~ignite.handlers.checkpoint.BaseSaveHandler` and optionally implement ``remove`` method
             to keep a fixed number of saved checkpoints. In case if user needs to save engine's checkpoint on a disk,
             ``save_handler`` can be defined with :class:`~ignite.handlers.DiskSaver`.
-        evaluator (Engine): evaluation engine used to provide the score
-        models (nn.Module or Mapping): model or dictionary with the object to save. Objects should have
+        evaluator: evaluation engine used to provide the score
+        models: model or dictionary with the object to save. Objects should have
             implemented ``state_dict`` and ``load_state_dict`` methods.
-        metric_name (str): metric name to use for score evaluation. This metric should be present in
+        metric_name: metric name to use for score evaluation. This metric should be present in
             `evaluator.state.metrics`.
-        n_saved (int, optional): number of best models to store
-        trainer (Engine, optional): trainer engine to fetch the epoch when saving the best model.
-        tag (str, optional): score name prefix: `{tag}_{metric_name}`. By default, tag is "val".
-        **kwargs: optional keyword args to be passed to construct :class:`~ignite.handlers.checkpoint.Checkpoint`.
+        n_saved: number of best models to store
+        trainer: trainer engine to fetch the epoch when saving the best model.
+        tag: score name prefix: `{tag}_{metric_name}`. By default, tag is "val".
+        kwargs: optional keyword args to be passed to construct :class:`~ignite.handlers.Checkpoint`.
 
     Returns:
         A :class:`~ignite.handlers.Checkpoint` handler.
@@ -646,15 +646,15 @@ def save_best_model_by_val_score(
     Models with highest metric value will be retained.
 
     Args:
-        output_path (str): output path to indicate where to save best models
-        evaluator (Engine): evaluation engine used to provide the score
-        model (nn.Module): model to store
-        metric_name (str): metric name to use for score evaluation. This metric should be present in
+        output_path: output path to indicate where to save best models
+        evaluator: evaluation engine used to provide the score
+        model: model to store
+        metric_name: metric name to use for score evaluation. This metric should be present in
             `evaluator.state.metrics`.
-        n_saved (int, optional): number of best models to store
-        trainer (Engine, optional): trainer engine to fetch the epoch when saving the best model.
-        tag (str, optional): score name prefix: `{tag}_{metric_name}`. By default, tag is "val".
-        **kwargs: optional keyword args to be passed to construct :class:`~ignite.handlers.checkpoint.Checkpoint`.
+        n_saved: number of best models to store
+        trainer: trainer engine to fetch the epoch when saving the best model.
+        tag: score name prefix: `{tag}_{metric_name}`. By default, tag is "val".
+        kwargs: optional keyword args to be passed to construct :class:`~ignite.handlers.Checkpoint`.
 
     Returns:
         A :class:`~ignite.handlers.Checkpoint` handler.
@@ -678,10 +678,10 @@ def add_early_stopping_by_val_score(
     Metric value should increase in order to keep training and not early stop.
 
     Args:
-        patience (int): number of events to wait if no improvement and then stop the training.
-        evaluator (Engine): evaluation engine used to provide the score
-        trainer (Engine): trainer engine to stop the run if no improvement.
-        metric_name (str): metric name to use for score evaluation. This metric should be present in
+        patience: number of events to wait if no improvement and then stop the training.
+        evaluator: evaluation engine used to provide the score
+        trainer: trainer engine to stop the run if no improvement.
+        metric_name: metric name to use for score evaluation. This metric should be present in
             `evaluator.state.metrics`.
 
     Returns:
diff --git a/ignite/contrib/engines/tbptt.py b/ignite/contrib/engines/tbptt.py
--- a/ignite/contrib/engines/tbptt.py
+++ b/ignite/contrib/engines/tbptt.py
@@ -57,19 +57,22 @@ def create_supervised_tbptt_trainer(
     `tbtt_step` time steps.
 
     Args:
-        model (`torch.nn.Module`): the model to train.
-        optimizer (`torch.optim.Optimizer`): the optimizer to use.
-        loss_fn (torch.nn loss function): the loss function to use.
-        tbtt_step (int): the length of time chunks (last one may be smaller).
-        dim (int): axis representing the time dimension.
-        device (str, optional): device type specification (default: None).
+        model: the model to train.
+        optimizer: the optimizer to use.
+        loss_fn: the loss function to use.
+        tbtt_step: the length of time chunks (last one may be smaller).
+        dim: axis representing the time dimension.
+        device: device type specification (default: None).
             Applies to batches.
-        non_blocking (bool, optional): if True and this copy is between CPU and GPU,
+        non_blocking: if True and this copy is between CPU and GPU,
             the copy may occur asynchronously with respect to the host. For other cases,
             this argument has no effect.
-        prepare_batch (callable, optional): function that receives `batch`, `device`,
+        prepare_batch: function that receives `batch`, `device`,
             `non_blocking` and outputs tuple of tensors `(batch_x, batch_y)`.
 
+    Returns:
+        a trainer engine with supervised update function.
+
     .. warning::
 
         The internal use of `device` has changed.
@@ -80,10 +83,6 @@ def create_supervised_tbptt_trainer(
 
         * `PyTorch Documentation <https://pytorch.org/docs/stable/optim.html#constructing-it>`_
         * `PyTorch's Explanation <https://github.com/pytorch/pytorch/issues/7844#issuecomment-503713840>`_
-
-    Returns:
-        Engine: a trainer engine with supervised update function.
-
     """
 
     def _update(engine: Engine, batch: Sequence[torch.Tensor]) -> float:


Test patch: