Automatically generated toctree for methods and classes

[vfdev-5]

🚀 Feature

Idea is to replace our manually created toctree for metrics, handlers, regression metrics etc.

How to do that :

• check .. autosummary:: tag in Sphinx
• add it and configure for each listed above .rst file : metrics.rst, handlers.rst etc

Example of usage:

• https://numpy.org/devdocs/reference/arrays.ndarray.html#id1
• https://github.com/numpy/numpy/blob/master/doc/source/reference/arrays.rst (edited)

This issue maybe or maybe not blocked by #1272

For Hacktoberfest contributors, feel free to ask questions for details if any and say that you would like to tackle the issue.
Please, take a look at CONTRIBUTING guide.

[theodumont]

Hi @vfdev-5, could I work on this one? If possible in the context of the Hacktoberfest, so I guess I'll have to wait until October before submitting a PR!

[vfdev-5]

Hi @theodumont sure, you can work on this issue ! However, it can be possible that exposed idea can not be doable with Sphinx version we have... Anyway, it worth to check.
About the Hacktoberfest,

September is Preptember – a full month for maintainers to groom your repositories and for contributors to learn about making quality pull requests.

Contributions during September don't count toward Hacktoberfest. Only pull requests submitted between October 1st to 31st will count.

So, technically, everyone can do a warm-up in September to understand better the project and its standard, guidelines etc and thus, have more chances to get October PRs accepted.

Concerning this issue, you can try thing locally and report here about how it is going. Then if everything seem to work, you can send the PR in October.

I'll assign you this issue such that others could know.

[theodumont]

Ok, great!
I'll keep you updated about how it goes locally.

[theodumont]

Hi @vfdev-5, I tried to make it work locally.

Replacing the actual

Complete list of metrics
------------------------

    - :class:`~ignite.metrics.Accuracy`
    - :class:`~ignite.metrics.Average`
    - [...]

by

Complete list of metrics
------------------------

.. currentmodule:: ignite.metrics

.. autosummary::
    Accuracy
    Average
    [...]

produces this output when built:

and we could specify a :template: option for the autosummary to customize the rendering of the .rst file.

But we still need to manually specify the classes and functions we want to appear in the list.
Is that what you wanted? I read about the :recursive: option (here), which may be what you're looking for, but I'm not sure. In any case, it is not available for sphinx versions below 3.1, but this may be a good way to simulate this?

Please tell me if I'm going in the wrong direction.
Thanks!

[vfdev-5]

@theodumont sorry for delay. Thanks for working on this issue! Yes, initial idea is to replace manually added items to automatically generated things.

In any case, it is not available for sphinx versions below 3.1

Can you check if we can easily upgrade to 3.1 version ?

[theodumont]

Running

pip install Sphinx==3.1
make html

raises no error, and the docs are generated. Is it enough to say that upgrading to 3.1 version is doable?

[vfdev-5]

@theodumont this sounds good ! Can you then check if we can generate the docs like we do it in travis:

ignite/.travis.yml

Lines 70 to 75 in 3f8daaf

	install:
	- pip install -r docs/requirements.txt
	- pip install git+https://github.com/vfdev-5/sphinxcontrib-versioning.git
	script:
	- sphinx-versioning --use-master-conf --use-master-templates build --greatest-tag --whitelist-branches master docs/source docs/build/html

but with Sphix==3.1

If everything is OK, you can send a PR and once #1270 (comment) "Nice to have" part is done, we can even preview newer version.

[theodumont]

Great, I just run these commands and except a few minor rst syntax warnings that were already there before, it seems to work.

A few warning lines that weren't written when running the travis scripts with the old version of Sphinx caught my attention though:

C:\Users\...\tmpmi9anx3rsphinxcontrib_versioning\61b425286ba89092ba0390b9c2d5a26d3d579ef2\ignite\engine\engine.py:docstring of ignite.engine.engine.Engine:1: WARNING: duplicate object description of ignite.engine.engine.Engine, other instance in engine, use :noindex: for one of them
C:\Users\...\tmpmi9anx3rsphinxcontrib_versioning\61b425286ba89092ba0390b9c2d5a26d3d579ef2\ignite\engine\engine.py:docstring of ignite.engine.engine.Engine:7: WARNING: duplicate object description of ignite.engine.engine.Engine.state, other instance in engine, use :noindex: for one of them
# etc...
C:\Users\...\tmpmi9anx3rsphinxcontrib_versioning\61b425286ba89092ba0390b9c2d5a26d3d579ef2\ignite\engine\engine.py:docstring of ignite.engine.engine.Engine.terminate_epoch:1: WARNING: duplicate object description of ignite.engine.engine.Engine.terminate_epoch, other instance in engine, use :noindex: for one of them

Do you think this is a big deal?

Awesome for the preview thanks to #1270 (comment)!

[vfdev-5]

Thanks for the update @theodumont !

Do you think this is a big deal?

Good question, I do not know. I'd say if all links and text are present, let's ignore the warning. Otherwise, maybe we should google them...

Awesome for the preview thanks to #1270 (comment)!

Yeah, I'd like to have preview working to see how it is with sphinx 3.1.

Anyway, please send a PR to close #1272 issue with just sphinx version update. Thanks !