5 ms·

A Sphinx plugin[0] allows for writing in markdown, and I'd heavily encourage using it if you're looking to get widespread adoption of sphinx on a project or at

A Sphinx plugin[0] allows for writing in markdown, and I'd heavily encourage using it if you're looking to get widespread adoption of sphinx on a project or at a workplace. Rst is fine once you learn it but removing barriers to entry is useful. [0] https://www.sphinx-doc.org/en/master/usage/markdown.html https://www.sphinx-doc.org/en/master/usage/markdown.html

kaycebasques 3y ago
The value prop of Sphinx goes down a lot if you're not using reST because you can't use the extensive catalog of directives, such as the ref directive that I mentioned in my first comment. If you must use Markdown then there's not much difference between Sphinx and all the other Markdown-powered SSGs out there. In other words there's not a compelling reason to use Sphinx if you've got to use Markdown. From Sphinx's Getting Started page: > Much of Sphinx’s power comes from the richness of its default plain-text markup format, reStructuredText, along with its significant extensibility capabilities. https://www.sphinx-doc.org/en/master/usage/quickstart.html#getting-started https://www.sphinx-doc.org/en/master/usage/quickstart.html#g...
- lrobinovitch 3y ago
  Myst has parity with most reST features and is equivalent to markdown for users not using those features: https://myst-parser.readthedocs.io/en/v0.13.7/using/syntax.html https://myst-parser.readthedocs.io/en/v0.13.7/using/syntax.h...
  - kaycebasques 3y ago
    Oh cool I need to revisit MyST then. I thought it didn't support cross-references but it looks like I'm wrong: https://myst-parser.readthedocs.io/en/v0.13.7/using/syntax.html#targets-and-cross-referencing https://myst-parser.readthedocs.io/en/v0.13.7/using/syntax.h... I will have to dig into exactly how much parity we're talking here but if it's very strong parity then I redact my previous statement Thanks for correcting me!
    - jw_cook 3y ago
      It works with all docutils and Sphinx roles, and almost all directives, including extensions. A notable exception is autodoc (automodule, autoclass, etc.), and any other directives that generate more rST. The current workaround is to use eval-rst: https://myst-parser.readthedocs.io/en/latest/syntax/code_and_apis.html#sphinx-ext-autodoc https://myst-parser.readthedocs.io/en/latest/syntax/code_and... Some more discussion about that in these issues: https://github.com/executablebooks/MyST-Parser/issues/163 https://github.com/executablebooks/MyST-Parser/issues/163 https://github.com/sphinx-doc/sphinx/issues/8018 https://github.com/sphinx-doc/sphinx/issues/8018

kaycebasques 3y ago

The value prop of Sphinx goes down a lot if you're not using reST because you can't use the extensive catalog of directives, such as the ref directive that I mentioned in my first comment. If you must use Markdown then there's not much difference between Sphinx and all the other Markdown-powered SSGs out there. In other words there's not a compelling reason to use Sphinx if you've got to use Markdown. From Sphinx's Getting Started page: > Much of Sphinx’s power comes from the richness of its default plain-text markup format, reStructuredText, along with its significant extensibility capabilities. https://www.sphinx-doc.org/en/master/usage/quickstart.html#getting-started https://www.sphinx-doc.org/en/master/usage/quickstart.html#g...

lrobinovitch 3y ago
Myst has parity with most reST features and is equivalent to markdown for users not using those features: https://myst-parser.readthedocs.io/en/v0.13.7/using/syntax.html https://myst-parser.readthedocs.io/en/v0.13.7/using/syntax.h...
- kaycebasques 3y ago
  Oh cool I need to revisit MyST then. I thought it didn't support cross-references but it looks like I'm wrong: https://myst-parser.readthedocs.io/en/v0.13.7/using/syntax.html#targets-and-cross-referencing https://myst-parser.readthedocs.io/en/v0.13.7/using/syntax.h... I will have to dig into exactly how much parity we're talking here but if it's very strong parity then I redact my previous statement Thanks for correcting me!
  - jw_cook 3y ago
    It works with all docutils and Sphinx roles, and almost all directives, including extensions. A notable exception is autodoc (automodule, autoclass, etc.), and any other directives that generate more rST. The current workaround is to use eval-rst: https://myst-parser.readthedocs.io/en/latest/syntax/code_and_apis.html#sphinx-ext-autodoc https://myst-parser.readthedocs.io/en/latest/syntax/code_and... Some more discussion about that in these issues: https://github.com/executablebooks/MyST-Parser/issues/163 https://github.com/executablebooks/MyST-Parser/issues/163 https://github.com/sphinx-doc/sphinx/issues/8018 https://github.com/sphinx-doc/sphinx/issues/8018