Hacker News Reader

Comment by morty_s | Hacker News Reader

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

View on HN

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

Worth noting that the de facto markup in python docstrings is RST

https://www.python.org/dev/peps/pep-0287/

You 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/exam...

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

> as far as I know the only existing implementation is in python

Pandoc supports rST.

I 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

Where I've automatically marshalled zig code into the elixir documentation (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

Reply on news.ycombinator.com