Document how to write a References section in examples #19232

Activity

1. timhoffm

   added

   Documentation

   on Jan 4, 2021
2. timhoffm

   self-assigned this

   on Jan 4, 2021
3. ianhi commented on Jan 4, 2021

   

   ianhi

   on Jan 4, 2021

   Contributor

   More actions

   Consider adding the possibility for linking between examples. Is this technically only a ".. seealso::" directive?

   I think ideally there would be a minigallery defined by the example. Though im not sure sphinx-gallery supports that.
4. rajpratyush commented on Mar 16, 2021

   

   rajpratyush

   on Mar 16, 2021

   Contributor

   More actions

   @timhoffm does this issue needs work?
5. timhoffm commented on Mar 16, 2021

   

   timhoffm

   on Mar 16, 2021

   MemberAuthor

   More actions

   Yes it does.

   There are multiple things to do here:

   The trivial thing would be to just write down what we're currently doing. See, e.g. https://matplotlib.org/devdocs/gallery/lines_bars_and_markers/fill.html#references.

   However this is more like a hack with several drawbacks, which is why I'm a bit hesitant to document it as the recommended solution

   • You need to put import matplotlib in
   • You get the Out[] line.
   • You have to mention pyplot as well as Axes to get references in both docs.

   Also, I had the impression that this way of writing code and let sphinx gallery discover it does not always work, but I cannot point at an example right now.

   The good solution would be to write a sphinx directive

   .. gallery-reference::
      matplotlib.axes.Axes.fill
      matplotlib.pyplot.fill
      matplotlib.axes.Axes.axis
      matplotlib.pyplot.axis
   

   That'd possibly be need to be done upstream in sphinx-gallery.
6. timhoffm commented on Mar 25, 2021

   

   timhoffm

   on Mar 25, 2021

   MemberAuthor

   More actions

   Proposal: Switch to

   ###############################################################################
   #
   # .. admonition:: References
   #
   #    The use of the following functions, methods, classes and modules is shown
   #    in this example:
   #
   #    - `matplotlib.axes.Axes.fill` / `matplotlib.pyplot.fill`
   #    - `matplotlib.axes.Axes.axis` / `matplotlib.pyplot.axis`
   

   Which results in

   

   This works without defining any new directives.

   For comparison: Current look

   
7. timhoffm

   added a commit that references this issue on Mar 25, 2021

   Document how to create sphinx-gallery references to examples

   ...

   This issue will close once commit 246210a is merged into the 'main' branch.

   246210a
8. QuLogic

   closed this as completedin #19774on Mar 26, 2021