ENH: Adding dropdown panels to the documentation

[HaoZeke]

🚀 The feature, motivation and pitch

Motivation

I've been writing up a small document on NumPy compatibility over at #71688 and one of the things which stood out is that there is no current mechanism to provide optional details without directing the reader to an issue or pull request comment. In that PR, the optional details would be this block describing the code path taken upon execution of the example; which was adapted from this issue comment.

Pitch

We need a documentation structure which is:

• Optional --> The remaining text should not rely on the contexts of this portion of the document
• Unobtrusive --> The documentation should be easy to avoid and must not break the flow of the current text

Solution

The solution is an additional information / details dropdown element which can be implemented easily with sphinx-panels (found here). For a completely contrived example:

.. dropdown:: Click on me to see my content!

    I'm the content which can be anything:

    .. link-button:: https://example.com
        :text: Like a Button
        :classes: btn-primary

Will render to the pleasantly optional:

Additionally, as the PyTorch documentation already loads Bootstrap classes, we don't add anything heavy in terms of the CSS / JS dependencies.

Alternatives

The current mechanisms for adding context to the main document are:

• Admonitions (note, warning, etc.)
• Footnotes

Neither of these are suitable for the kind of detail provided by a dropdown. Admonitions break the flow of the text and are always used to highlight text, while footnotes can be jarring to work with for long documents, and the diminished font-size make it impractical for longer discussions.

Additional context

See #73836 for an implementation.

Pinging @rgommers for comments.