5 ms·

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 th

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

dnautics 7y ago
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.
- 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 ago
    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/example_google.html https://sphinxcontrib-napoleon.readthedocs.io/en/latest/exam...
  - c-cube 7y ago
    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.
    - 39CA1814 7y ago
      > as far as I know the only existing implementation is in python Pandoc supports rST.
  - dnautics 7y ago
    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 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

dnautics 7y ago

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.

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 ago
  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/example_google.html https://sphinxcontrib-napoleon.readthedocs.io/en/latest/exam...
- c-cube 7y ago
  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.
  - 39CA1814 7y ago
    > as far as I know the only existing implementation is in python Pandoc supports rST.
- dnautics 7y ago
  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 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