5 ms·
I can't stand reStructuredText, it's obtuse. Over the last year or so have converted all of our documentation to Markdown and I couldn't be happier about it.
by drcongo 7y ago
I can't stand reStructuredText, it's obtuse. Over the last year or so have converted all of our documentation to Markdown and I couldn't be happier about it.
- afroisalreadyin 7y agoTotally agree. rst is feature-rich but very difficult to get right. You practically need the documentation open at all times. I would rather write (and read) documentation in txt, with links as footnotes.
- morty_s 7y agoYep. Was going to say the same thing. IMO Sphinx and rst is a bad experience. Markdown _is_ simple—that’s what is great about it. I’m also a fan of languages that support markdown in comments/in-source-documentation (rust, elixir, etc.)
- dnautics 7y agoNot only that, but elixir docs will automatically search markdown for appropriate content in backticks and hyperlink corresponding code (in elixir STD lib, erlang std lib, and I believe dependencies) for you. That's much harder to do in rst.
- corndoge 7y agoWorth noting that the de facto markup in python docstrings is RST https://www.python.org/dev/peps/pep-0287/ https://www.python.org/dev/peps/pep-0287/
- drcongo 7y agoYou can also use the Google style [1], which we do because it's not RST so it's actually readable by humans. https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html https://sphinxcontrib-napoleon.readthedocs.io/en/latest/exam...
- c-cube 7y agoBut rST is deeply linked to python: as far as I know the only existing implementation is in python, the touted "extensibility" is based on python, etc. Other languages don't seem to adopt rST because they don't have this deep relationship with it. Markdown has a lot of implementations (with some fragmentation, granted) and is adopted by many diverse projects outside the python sphere.
- 39CA1814 7y ago> as far as I know the only existing implementation is in python Pandoc supports rST.
- dnautics 7y agoI mean look if you want to compare overall python doc quality vs elixir doc quality (especially for community projects)... I write Elixir docs on my projects because it's easy pretty and obsessively making my docs prettier hits that spot in my brain. Extreme example: https://hexdocs.pm/zigler/Zigler.html https://hexdocs.pm/zigler/Zigler.html Where I've automatically marshalled zig code into the elixir documentation (https://hexdocs.pm/zigler/beam.html#get_f32/2 https://hexdocs.pm/zigler/beam.html#get_f32/2) and you can click the slash in the upper right of the function header to link to the code on Github. As a bonus, check it out on mobile and compare it to this on mobile: https://docs.python.org/3/library/functions.html https://docs.python.org/3/library/functions.html
- corndoge 7y agoI've had the markdown vs rst discussion with a few people a few times and the pro-markdown people always cite this, saying rst is much harder to use or the core syntax is awkward in comparison. I don't really understand this, the same markup you get from markdown has about the same surface area in terms of syntax in rst. `code` vs ``code``, or just an indented block (in rst just add :: before the block start), emph is still emph, you can still use = and - for headers, bullet lists are the same as markdown, and so on. Inline hyperlinks are about the only thing that aren't visually nice like they are in markdown, (text)[link] vs <text `link`>_ or w/e it is (I use sphinx refs so I don't recall exactly). Actually in a way rst is better for links since the common thing in markdown is to reference links like this[0], in RST with _ instead that actually works and this becomes a hyperlink. Like the basic features are mostly identical. But then when you start needing features for big documents like cross references, highlighted syntax blocks, images, ToC, figures, etc it RST has all that built in and you don't have to reach for some markdown superset (although I guess you could argue Sphinx is that for RST). I dunno, I've done both and I just have a much better time with RST once the project size gets past a single doc. I still use md for READMEs and gists and whatnot, I guess my point is, different tools for different jobs, if you have to pull weeds in your garden use a spade, if you have to do it for a field use a machine, or something.
- oefrha 7y agoPlease enlighten me on how to produce [`code`](https://example.com https://example.com) in reST. Hint: This is rhetorical. https://docutils.sourceforge.io/FAQ.html#is-nested-inline-markup-possible https://docutils.sourceforge.io/FAQ.html#is-nested-inline-ma...
- njharman 7y agoJust the opposite. Hate the markdowns. ReST for life!