I think(?) sphinx-gallery requires both a title and some non-empty "content", right? Would it be better to ask them (or write a PR ourselves) that drops the requirement for the content (generating a page with just a title and a plot) and/or special cases the case of the a single-line docstring to use it as both title and content?

I feel that docstrings of the form

======
<topic>
======

This example showcases <topic>.

or

======
<topic>
======

Reference for <topic> included in matplotlib.

are mostly line noise...

(As a side note I think that the correct capitalization is matplotlib, not Matplotlib -- see home page, for example.)

(As a side note I think that the correct capitalization is matplotlib, not Matplotlib -- see home page, for example.)

Not sure that discussion was ever concluded.

sphinx-gallery is very unlikely to drop that requirement considering it is a very good way to enforce good documentation and meaningful examples. I'll ask one of the maintainer if this is an option but don't hold your breath.

for the matplotlib versus Matplotlib, considering these are lines that were there before me, I'd rather not have to modify them. I am going for the minimal change possible on all examples to precisely make the PR mergeable quickly and without discussion.

I agree that the requirement is, in theory, good. In practice, repeating the title in the description is somewhat defeating its goal...

Sorry for the capitalization noise :)

@anntzer I might create a PR fixing the capitalization as that's a quick easy fix.

I am a bit concerned about renaming examples breaking people's bookmarks.

Why not backport example-only changes as far back as we can? That way the next time we re-generate the docs (ex on a micro release) the updated examples will be built.

If we migrate to sphinx-gallery, this will not be an option: examples are split between the one that produce a plot and no plot (and I hope soon, a video). This can be done right at the end, specially considering @efiring mentioned cleaning up and removing some of our examples (we have around 450 examples right now…).

(I can easily revert this change).

@tacaswell eh… I hadn't seen/understood your comments on the milestone.
I clearly don't understand how matplotlib deals with tagging, branching and releasing. On all the other opensource projects I've worked on once you've branched and tagged, the minimal amount of changes are backported. This means only backporting critical bug fixes. We actually had agreed to this in one of the calls (also mentionning a quick 2.1 release after the 2.0).
The constant backporting of pull requests by everyone, and then the merge of 2.0 into master really raises red flags in terms of project maintenance and good practices : as everyone can (and does) backport elements to 2.x, we've been backporting new features and very minor bug fixes to the 2.0 branch (which then leads to more bugs to fix in the 2.0 branch, so more delays to 2.0 etc).

Documentation is as important as code. It needs to be checked, reviewed and maintained. IMO, backporting documentation and examples changes should not be taken lightly. Instead of backporting to 2.0, I think we should be thinking about 2.1.

All of our examples should be producing a plot and the name pattern sphinx-gallery looks for is configurable (ex https://github.com/NSLS-II/docs/blob/master/source/conf.py#L68 from my day-job).

The criteria for backports onto the RC should be critical or low risk. Doc changes (particularly to examples or rst prose) can not break anyone's code so are zero-risk.

I don't see what is wrong with merging maintenance branches up into the master branch.

I've reverted the change in filenames, but it will be impossible to migrate to sphinx-gallery without a way to distinguish examples that produces plots to those that don't from the filename.

Current coverage is 62.09% (diff: 100%)

Merging #7327 into master will not change coverage

@@             master      #7327   diff @@
==========================================
  Files           174        174          
  Lines         56050      56050          
  Methods           0          0          
  Messages          0          0          
  Branches          0          0          
==========================================
  Hits          34807      34807          
  Misses        21243      21243          
  Partials          0          0          

Powered by Codecov. Last update 4d390fa...4e25744

I am closing this PR.
If someone is interested in picking up the work, the branch is still available.

This is ready to be merged.

Backported v2.0.x as 38298db

Thanks @NelleV, these are great improvements! I'm really looking forward to helping more with migrating to sphinx-gallery