The only thing I would keep is „Inserting matplotlib figures“. That’s specific to us. Everything else is standard Sphinx and I don’t see a reason why we should bother to maintain that.

Here's a proposal:

• Moving the mpl specific stuff to https://matplotlib.org/stable/devel/documenting_mpl.html
• Linking to the official Sphinx tutorial https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

Is this a reasonable way to move forward?

EDIT: Fixed the link to the sphinx/reST tutorial.

I'm gonna close this b.c. I think everything in that guide that's mpl specific is already in the doc docs, but folks are free to reopen if there's something they really want. The format here is sampledoc->doc docs

• Getting started -> https://matplotlib.org/devdocs/devel/document.html#getting-started
  • Installing your doc directory -> https://matplotlib.org/devdocs/devel/document.html#build-the-docs
• Customizing the look and feel of the site ->https://matplotlib.org/devdocs/devel/document.html#navbar-and-style
• Sphinx extensions for embedded plots, math and more
  • ipython sessions -> far as I can tell, ipython now ships w/ this lexer for pygments
  • Using math->https://matplotlib.org/devdocs/devel/document.html#tools-for-writing-mathematical-expressions
  • Inserting matplotlib plots-> https://matplotlib.org/devdocs/devel/document.html#add-figures
  • Inheritance diagrams->https://matplotlib.org/devdocs/devel/document.html#generate-inheritance-diagrams
  • This file
• Ipython Directive -> this is cool but not mpl
  • Pseudo-Decorators
  • Sphinx source for this tutorial
• Sphinx cheat sheet -> should condense but that's a [Doc]: Sort out doc mechanics/formatting/content guides #26392 problem
  • Formatting text -> https://matplotlib.org/devdocs/devel/document.html#write-rest-pages
  • Making a list -> https://matplotlib.org/devdocs/devel/style_guide.html#lists
  • Making a table -> https://matplotlib.org/devdocs/devel/style_guide.html#tables, https://matplotlib.org/devdocs/devel/document.html#table-formatting
  • Making links-> https://matplotlib.org/devdocs/devel/document.html#refer-to-other-documents-and-sections
  • This file
• Emacs ReST support -> as an emacs fan, we don't provide keybindings for anything else
  • Emacs helpers

Upside of doing this exercising is understanding where https://matplotlib.org/devdocs/devel/document.html#miscellaneous came from and I think I'm gonna put those back to where they were in the sampledoc structure.

I agree @story645 and after writing this proposal had been thinking of using it as an opportunity to review those docs but I think those are in good shape today. Thanks!

Jaunita gave some good feedback on the dev docs/doc docs at sprints that I wanted to start implementing so spun back to this as part of that 😅 #28578 is first stage.