Toctrees for classes and methods using sphinx autosummary

[trsvchn]

Fixes #1273

Description:

Adds toctrees for classes and methods for several ignite modules

Check list:

• New tests are added (if a new feature is added)
• New doc strings: description and/or example code are in RST format
• Documentation is updated (if required)

[vfdev-5]

@trsvchn thanks for the PR ! Looks very nice when rendered: https://deploy-preview-1393--pytorch-ignite-preview.netlify.app/

However, we still need to add all items manually, do you think if there is a way to automatically generate those lists without manual inserting ?

[vfdev-5]

I know that this is a bit out of the scope of the PR, but I think it would be better to create a complete list for the whole module ignite.contrib.metrics vs only regression metrics. If you wish to do that in another PR, it is up to you.

[trsvchn]

@trsvchn thanks for the PR ! Looks very nice when rendered: https://deploy-preview-1393--pytorch-ignite-preview.netlify.app/

However, we still need to add all items manually, do you think if there is a way to automatically generate those lists without manual inserting ?

@vfdev-5 I've found another possible solution, so I am going to try it

[trsvchn]

@vfdev-5 Well, I think I've found the solution, after inspecting autosummary I've spotted the place to modify, and prepare a patch for original autosummary, it takes a module (a current module) and generate summary table for classes and function from that module automatically!

Here is how to use it, there are 3 new options:

:autolist: - list classes and functions

    .. currentmodule:: module
 
    .. autosummary::
        :toctree:
        :nosignatures:
        :autolist:

autolist-classes: to list only classes

    .. currentmodule:: module
   
    .. autosummary::
        :toctree:
        :nosignatures:
        :autolist-classes:

autolist-functions - if you need just functions

    .. currenrmodule:: module

    .. autosummary::
        :toctree:
        :nosignatures:
        :autolist-functions:

But note, using .. currentmodule:: <module> before autolist is required, for example for metrics

    .. currentmodule:: ignite.metrics

    .. autosummary::
        :toctree:
        :nosignatures:
        :autolist-functions:

[vfdev-5]

@trsvchn looks super cool ! I was just wondering if we could make item's height inside auto summary list a bit smaller ?
For example, the list of metrics here: https://deploy-preview-1393--pytorch-ignite-preview.netlify.app/metrics.html#complete-list-of-metrics can not be displayed entirely on the display. Maybe, we can try to remove class description, e.g. "Base class for all Metrics." for Metric. What do you think ?

[trsvchn]

@vfdev-5 Maybe we can try to play with css, like here, I changed col width in such way, I hope we can do the same for the row height?

ignite/docs/source/_templates/_static/css/ignite_theme.css

Lines 128 to 136 in 86bf414

	/* automatically generated toctree tables */
	article.pytorch-article table.longtable.docutils.align-default colgroup {
	display: none;
	}
	article.pytorch-article table.longtable.docutils.align-default tbody td:first-child {
	width: 30%;
	}

[vfdev-5]

@trsvchn true, finetuning css can be an option too. There are however cases where the description take multiple lines. Is it more simple to remove description or it is a similar difficulty ?

[trsvchn]

@vfdev-5 I am going to try to generate rows for items without description, Let's see what happens

[trsvchn]

@vfdev-5 Here what we have

[vfdev-5]

Seems like summary now contains python classes and private members

[trsvchn]

Yeah, here is some dummy test with a lot of classes with no descriptions:

Looks like this is css issue

[trsvchn]

Ok, we are getting closer :)

article.pytorch-article table.longtable.docutils.align-default tbody td {
  padding: 0.1rem;
}

But I am not sure

[trsvchn]

@vfdev-5 Finetuning CSS, What do think?

[vfdev-5]

@trsvchn looks awesome ! I'm wondering about how works BetterAutosummary and at which step docstring is added ? For example, if we could trim the description to say 50 char and add "..."

[trsvchn]

@vfdev-5 BetterAutosummary works before docstrings extraction, Autosummary does that. I can take a look what we can do.

[vfdev-5]

Thanks ! I think we can update this PR with modified CSS and docstring reduction can be done in a another PR

[trsvchn]

Yeah! Now it fits to the display)

[vfdev-5]

@trsvchn looks like Autosummary.get_items(self, names) is responsible for doctring and outputs: [(name, signature, summary_string, real_name), ...]. Probably, we can try overriding it and just cut summary_string as we wish....

[trsvchn]

@trsvchn looks like Autosummary.get_items(self, names) is responsible for doctring and outputs: [(name, signature, summary_string, real_name), ...]. Probably, we can try overriding it and just cut summary_string as we wish....

Oh, Thanks! I am going to try!

[vfdev-5]

And is it CSS where it is defined the size of the field for class/function name and the description ?
We have a very long name for a regression metric : https://deploy-preview-1393--pytorch-ignite-preview.netlify.app/contrib/metrics.html#module-ignite.contrib.metrics.regression
I was thinking if we can make the first column a bit larger (in another PR certainly)

[vfdev-5]

I also remarked locally when building that there is a large list of warnings like

 WARNING: autosummary: stub file not found 'ignite.utils.manual_seed'. Check your autosummary_generate setting.

do you think we can do something with that ?

[trsvchn]

This sets width of the first column, that contains members name, so now 30%

article.pytorch-article table.longtable.docutils.align-default tbody td:first-child {
  width: 30%;
}

[trsvchn]

I also remarked locally when building that there is a large list of warnings like

 WARNING: autosummary: stub file not found 'ignite.utils.manual_seed'. Check your autosummary_generate setting.

do you think we can do something with that ?

Yeah, I am thinking about it

[trsvchn]

@vfdev-5 ok, trimming works but sometimes it trims class names or methods:

Metric	Base class for all Metrics….
Accuracy	Calculates the accuracy for binary, multiclass and multilabe…
Loss	Calculates the average loss according to the passed loss_fn….
MetricsLambda	Apply a function to other metrics to obtain a new metric….
MeanAbsoluteError	Calculates the mean absolute error….
MeanPairwiseDistance	Calculates the mean pairwise distance: average of pairwise d…
MeanSquaredError	Calculates the mean squared error….
ConfusionMatrix	Calculates confusion matrix for multi-class data….
TopKCategoricalAccuracy	Calculates the top-k categorical accuracy….
Average	Helper class to compute arithmetic average of a single varia…
DiceCoefficient	Calculates Dice Coefficient for a given :class:`~ignite.metr…
EpochMetric	Class for metrics that should be computed on the entire outp…
Fbeta	Calculates F-beta score…
GeometricAverage	Helper class to compute geometric average of a single variab…
IoU	Calculates Intersection over Union using :class:`~ignite.met…
mIoU	Calculates mean Intersection over Union using :class:`~ignit…
Precision	Calculates precision for binary and multiclass data….
Recall	Calculates recall for binary and multiclass data….
RootMeanSquaredError	Calculates the root mean squared error….
RunningAverage	Compute running average of a metric or the output of process…
VariableAccumulation	Single variable accumulator helper to compute (arithmetic, g…
Frequency	Provides metrics for the number of examples processed per se…
SSIM	Computes Structual Similarity Index Measure…

[vfdev-5]

Oh, I see. That's bad :( OK, let's make something better than blind trimming later.
To merge this PR, I'd like to remove all warnings though.

[trsvchn]

Oh, I see. That's bad :( OK, let's make something better than blind trimming later.
To merge this PR, I'd like to remove all warnings though.

Yeah, 173 warnings is not an indicator of quality)

[trsvchn]

I think all these warnings because of toctree:

The toctree option also signals to the sphinx-autogen script that stub pages should be generated for the entries listed in this directive. The option accepts a directory name as an argument; sphinx-autogen will by default place its output in this directory. If no argument is given, output is placed in the same directory as the file that contains the directive.

I need to test if BetterAutosummary can work properly w.o toctree, maybe we don't need it.

[vfdev-5]

Thanks a lot for this awesome PR, @trsvchn !

I let CI finish its job and will merge after that.

[trsvchn]

That was interesting! I've improved my knowledge about python imports and finally learned how to inspect webpages)) very "interdisciplinary" issue)

[vfdev-5]

Yes, documentation issues are rather universal :) We could all learn from this PR, could be very helpful !

[vfdev-5]

@trsvchn I'm looking into those new lists and remark that non-documented helper functions like here :
https://pytorch.org/ignite/master/contrib/engines.html#ignite-contrib-engines

• empty_cuda_cache
• get_default_score_fn
• setup_any_logging (was removed today as was deprecated)

Could you please take a look at that on how to filter them too ? Thanks !

[trsvchn]

@vfdev-5 Sure, I'll look at it.

Oh, yeah, currently BetterAutosummary doesn't check module members for the presence of a doc strings. I think that;s the reason.