Use autodoc_typehints = "description" in conf.py

[ydcjeff]

📚 Documentation

EDITED HERE: As a help wanted issue, please, see below comment #1665 (comment) 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:

After:

Changing to this docs style needs a little work. It needs to

• add

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

[vfdev-5]

@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

[trsvchn]

@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.

[ydcjeff]

@vfdev-5 I will send PR tmr

@trsvchn yes, that description option is new in sphinx 3.1 so that we can do that

[sdesrozis]

@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.

[vfdev-5]

@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.

[ydcjeff]

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:

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.

[vfdev-5]

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.

[ydcjeff]

OK, then I will start with contrib.engines module.
On VSCode, you can use \(\w+.*(\s+\w+)*\): regex for search and replace.

Modules left to do:

• ignite.engine
• ignite.handlers
• ignite.metrics
• ignite.distributed
• ignite.utils
• ignite.contrib.engines
• ignite.contrib.metrics
• ignite.contrib.handlers