4 ms·
Worth 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/
by corndoge 7y ago
Worth 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