Issue

This is just a todo for continuing the improvement to devel/documenting_matlab #9872. Feel free to comment and I'll

I suggest an outline as below. Strars indicate some writing needed versus re-org.

The idea here is to explain rst first (because you need it for the rest), and then docstrings, and finally examples and tutorials.

• Getting started
  • Installing dependencies
  • Organization of documentation
  • Building the documentation
• Writing ReST pages and ReST sections of other documents.
  • ** Intro:
    • pure *.rst and rst in docstrings and scripts.
  • ** General format and conventions
    • Section name formatting
  • Linking to other rst pages
  • Linking to other code
  • Linking to data files
  • Generating inheritence diagrams
  • Emacs helpers.
• Writing self-documenting docstrings
  • General format
  • ** Matplotlib-specific conventions (Additions to the documentation guide #9875)
  • Function arguments
  • Setters and getters
  • Keyword arguments
  • ** Adding example code and figures (and where the figures go).
• Writing examples and tutorials
  • ** Simple example
  • ** Special tutorial hints
    • key-image

Note there is some overlap between the rst-specific stuff and the rest...