Proposal to create Markdown equivalent of specification

[stefanv]

Markdown is, by now, much more commonly used than ReST, and so I wonder if the time hasn't come for us to provide a markdown equivalent to the numpydoc format?

I've taken a first stab at it, and would love to hear what you think:

https://hackmd.io/_EKGyNRbQ2Sx_UJVqur2CA

In the end, the changes were fairly minimal, and can mostly be made with an automated tool.

Questions:

• Is this worth doing?
• If so:
  • Which header syntax to use? (I think the current underline syntax—valid markdown—works better than ##)
  • Are the custom introduced roles OK? ({param}, {func}, {class}, {obj}, etc.)
  • How do we signal to documentation engines which version we are using?

Improvements:

• I think turning single-backticks into an explicit {param}`x` solves a long confusing aspect: when to use single vs double backticks (the prior is for linking to parameters, the latter is for code, FWIW).