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).
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:
##){param},{func},{class},{obj}, etc.)Improvements:
{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).