Hacker News new | past | comments | ask | show | jobs | submit login

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

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




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


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




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: