After many weeks of work I think that the documentation is in a much better state now. I think that we are 80% of the way towards considering this "good enough" for now. This issue is a place to keep some lingering issues / ideas that could be implemented before 2.1 is released:

ToDo

• Cycler documentation
  Use of the cycler should be demoed more extensively in the examples, and should also be introduced and explained in an introductory tutorial. See scipy2017 sprint - docs #8885

• The developers guide should be updated and made more clear. outside the scope of this issue I think

• This blog post or something like it should be converted into a "getting started with matplotlib" kind of thing. Maybe we should reach out to the author and ask them to submit it as a sphinx-gallery python file.

• We need to go through all the open PRs that were working on sphinx gallery and make sure that they get either closed because the work has already been done, or merged soon otherwise they'll quickly become forgotten PRs.

In progress

• On that note the toolkits API pages should be generated with Autosummary so that we get auto-linking with the SG examples. (SG for toolkits #8573)
• toolkits should be sphinx-galleryified and put into their own folder within tutorials, or their own gallery. (SG for toolkits #8573)
• We should organize the examples folder so that the "most important" folders come first. We'll either need to wait for SG to support this, or add numbering to some examples folders. (being addressed partially here: [WIP] adding folder sorting sphinx-gallery/sphinx-gallery#233)
• Document the data kwarg, show how it is used in a tutorial and show some examples that use it. Ideally using pandas dataframes (I know it adds a dependency but I guarantee that users want to know how to do this) (adding keyword plotting #8566)
• Improve the screenshots page
  From @story645: I've been wanting a simple gallery of sorts that goes over the basic plot types - line, scatter, bar, pie, heatmap - in like 5 lines or less w/ nothing fancy and I think that'd be perfect for a tutorial type section.
  This is quite similar to the screenshots page, which is currently buried and kinda hard to find. IMO we should turn this into a plot types folder in the tutorials section, and have one short example for each plot type. (linking front thumbnails, updating screenshots + pyplot API page #8581 for starters)
• The PNGs generated for the front page should be instead pulled from the SG thumbnails, and clicking each one should take you to that example, not to the screenshots page. (linking front thumbnails, updating screenshots + pyplot API page #8581)
• Make sure that plotting with categorical values is clearly documented as it's being released with 2.1 (also here: use categorical in demos #7155 and taken care of in linking front thumbnails, updating screenshots + pyplot API page #8581 )

I think this will go a long way towards bringing MPL's documentation into the 21st century.

As a general thought, any time somebody writes a blog post that makes an incorrect assumption about matplotlib, e.g. this one, we should take a hard look at the docs and figure out how to make that feature/ use-case easier to find. In addition, any time somebody writes a clear, well-written blog post that is better at explaining things than the MPL docs, we should improve the docs or ask that person to contribute their post as a tutorial.

Let me know if there are any other suggestions for this issue and I can append to the list. Is there any ETA on 2.1? I wanna make sure this is a realistic goal.

@story645 @NelleV @tacaswell @phobson @anntzer @dopplershift @QuLogic