[doctest] Provide definition of `default_evaluator` and other default objects

📚 Documentation

It was already discussed and also pointed out in the forum that it is unclear how default objects are defined inside doctest examples. For example: https://pytorch.org/ignite/generated/ignite.metrics.Accuracy.html#ignite.metrics.Accuracy

metric = Accuracy()
metric.attach(default_evaluator, "accuracy")
y_true = torch.Tensor([1, 0, 1, 1, 0, 1])
y_pred = torch.Tensor([1, 0, 1, 0, 1, 1])
state = default_evaluator.run([[y_pred, y_true]])
print(state.metrics["accuracy"])

We can think of different solutions:

• 1. for all doctests, add a link on https://github.com/pytorch/ignite/blob/111fc7a0c57bb4d96d94f300f8c2f188f7bda148/docs/source/conf.py#L334-L378
• 1. visible code is as above but if code is copied we add automatically all defaults (not good as a solution)
• 1. other ideas ?

[DevPranjal]

Hi @vfdev-5 @sdesrozis, I was trying a few options to resolve this problem

Ideal solution would be to find how to make this code foldable (IMO, it shouldn’t be easy). So that once rendered we could have something like

I ended up with this using the sphinx_togglebutton extension

https://user-images.githubusercontent.com/72960463/153129453-84a1aeba-f0b8-4396-8059-e809cf9c181f.mp4

Currently, I am using code docstring below:

.. toggle::
   .. testcode::
        <defaults>
...

But as mentioned,

Ideally, we do not want to have all declarations to be present at each docstring, it would be better to predefine them somehow and while rendering the docs, add to the place where they should be

I tried the below, but was not able to get it to work:

.. toggle::        
     .. include:: defaults.rst
...

[vfdev-5]

@DevPranjal I just tried to use .. include:: directive here and looks like it works:

Can you try this in your fork to see if everything could work with toggle ?

Docs for include directive: https://docutils.sourceforge.io/docs/ref/rst/directives.html#include

EDIT: I think we have to manually copy defaults.rst to source/generated in order to be discovered from the docstring. I updated my fork. You can borrow the code from it and send a PR.