jbednar
commented
6 years ago The reason to favor markdown in particular is that the main developers on these projects spend a lot of time on GitHub and Jupyter, which both use markdown extensively. We're more likely to write correct syntax, more likely to notice incorrect syntax, and less likely to get confused, if we can all primarily stick to one markup language. (E.g. @philippjfr always seems to write .rst string literals in his markdown!) Compared to Github and Jupyter's immediate feedback for mistakes, docstrings give no feedback about formatting until randomly coming across them online months or years later, so it's crucial that we can write them in a language we know well. Alternatively, I wonder if there is a minor mode for Emacs that we could enable to format the docstrings to verify that their syntax is ok? Then it wouldn't matter so much what language they are in...
We should probably try to write pyviz project docstrings in a consistent way. Right now, some projects use rst, but not necessarily correctly or consistently. I believe there's a general feeling that if the docstrings need to use rst, they will forever be full of inconsistent and incorrect rst - markdown would be a more popular option.
Need to list the options available for writing docstrings. Here's a (very quick) start:
(everyone please feel free to edit)
Should also consider what various other projects do.