Proposal to create Markdown equivalent of specification

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).

Start by reading the linked HackMD proposal alongside the current numpydoc specification and its ReST conventions. Evaluate the proposed header syntax, custom roles, and version signaling, then determine whether the format is accepted and what documentation-engine changes would be required. Done means an agreed specification and implementation scope.