How to link the gallery

Hello. I’m fairly new to sphinx-gallery and sphinx in general, and here is my problem.

I created a plot_example.py script and placed it in my examples_dirs folder. As a result, I do see it copied in the gallery_dirs folder, that is, I get the file auto_examples/plot_example.py. Then, to include a link to the gallery in my main documentation page (index.rst), I have the line :doc:`Gallery <auto_examples/index>` However, when building the doc, I get: WARNING: undefined label: sphx_glr_auto_examples_plot_example.py (if the link has no caption the label must precede a section header) and indeed the link to this example is broken. What am I doing wrong?

[Titan-C]

Exactly what I imagined. In your example plot_example.py when you write the docstring you need to make the title a heading. Using rst syntax is just underlining it with something. That solves the problem.

 Circle plot.
+============
 
 Uses a function to plot a circle.

Now, I wonder why no exception is raised in this case.

[GkAntonius]

That’s it! Thank you Titan-C. Looking back at the sphinx-gallery documentation, the instructions were unequivocal:

The structure follows a leading docstring that must follow reStructuredText syntax and a header. Then the executable code of your script.

Yet, an example would have been helpful for sphinx newbies. Cheers!