Skip to main content

I want to write my #Python docstrings in #Markdown, but I can't seem to find a standardised workflow and format for doing so. I've come across a bunch of tools and scripts people have hacked together, and Stack Overflow answers telling me to write code to convert the Markdown to ReStructured Text so documentation tools can understand it.

Is this really so rare that I have to take on a boat load of complexity to make it work?

#python #markdown
This entry was edited (1 month ago)
in reply to James Scholes

Matt Campbell
Matt Campbell
• •
I suppose having reStructuredText be the only format for doc comments is consistent with the Python dictum that there should be one and only one obvious way to do it. I, too, would prefer Markdown though. RST's way of indicating headings is particularly inconvenient.
in reply to Matt Campbell

aaron
aaron
• •
@matt I just looked at this and... eww, gross.
@Matt Campbell
in reply to Sean Randall

Matt Campbell
Matt Campbell
• •
@cachondo @fireborn I wasn't going to say that because, as a partial still largely relying on my vision, I've been wrong before. I used to think that Python's significant whitespace would itself be a big problem for blind programmers.
@aaron @Sean Randall
in reply to Matt Campbell

aaron
aaron
• •
I can't think of a single way this isn't awful for speech or braille. 2 lines to communicate what can be communicated in 1 in markdown and ridiculous amounts of symbols.
This entry was edited (1 month ago)
in reply to Matt Campbell

Mikołaj Hołysz
Mikołaj Hołysz
• •
@matt @cachondo @fireborn IMO significant whitespace isn't that much of a problem, aligning things under parentheses would be. Thankfully, we have formatters that can do this for us nowadays.
@Matt Campbell @aaron @Sean Randall
in reply to Matt Campbell

James Scholes
James Scholes
• •
Meh. When making technical or project decisions, the so-called "Zen of Python" is rarely on my list of considerations, particularly given the recent behaviour of its primary author. The fact that there are at least four competing styles of ReST-like docstrings undermines it on its own.
This entry was edited (1 month ago)
⇧