[text](url)
`text <url>`_
[1] e.g. https://myst-parser.readthedocs.io/en/v0.13.7/using/syntax.h...
[0] https://www.sphinx-doc.org/en/master/usage/markdown.html
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#g...
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!
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...
Some more discussion about that in these issues:
What I really hope that exists, is a system where I can reuse the documentation (sections) in other pages, ergonomically
I built that system multiple times to do preprocessing with things like including parts or special linking or referencing images from anyhwere
https://github.com/xmonader/publishingtools/tree/development...
They are starting to work towards full sphinx functionality in myst markdown, too.
[1] https://myst-parser.readthedocs.io/en/latest/intro.html [1] https://executablebooks.org/en/latest/blog/2023/new-project-...
This podcast episode is worth a listen for anyone interested in these tools and where they're headed: https://talkpython.fm/episodes/show/354/sphinx-myst-and-pyth...
https://hieroglyph.readthedocs.io/en/latest/getting-started....
This meant I could first write a blog post on learning Clojure as a Pythonista[1]; then turn some code samples and tables and images into slides I could present at a public talk on my laptop or desktop[2]; and then finally publish a public notes document that talk attendees could use to easily study or copy-paste code examples[3]. (The notes are the exact same contents of the slides, just rendered in a simple single-page HTML format, with each slide transformed into a section heading, with permalinks/ToC auto-generated.) So, this is generated HTML from a single .rst source[4], all the way down! And, of course, I could version control and render the .rst file powering the slides / notes / etc. in GitHub.
[1]: https://amontalenti.com/2014/11/02/clojonic
[2]: https://amontalenti.com/pub/clojonic/
[3]: https://amontalenti.com/pub/clojonic/notes/
[4]: https://amontalenti.com/pub/clojonic/notes/_sources/index.tx...
Note: the slides in [2] do not play well on mobile. You are meant to use keyboard arrows to advance and tap “t” to switch into tiled mode (aka slide sorter) and “c” to open a presenter console. The slides are powered by a fork of html5slides, which will look familiar if you’ve seen the JS/CSS slide template that Go core developers use in https://go.dev/talks (they generate those with “go present,” a different tool, though).
More recently, I have also used a similar-in-spirit tool called marp (https://marp.app) for generating technical slides from source, but the output and functionality was never quite as good as rST + Sphinx + hieroglyph. The big advantages to marp: Markdown is used as the source, some tooling allows for VSCode preview, and PDF export is fully supported alongside HTML slides.
I have a soft spot for Sphinx, not only because it was responsible for so much great documentation of Python open source libraries (including Python’s own standard library docs at python.org), but also because the first comprehensive technical docs I ever wrote for a successful commercial product were written in Sphinx/rST. And the Sphinx-powered docs stayed that way for a ridiculously long time before being moved to a CMS.
I call it a docs system rather than static site generator because the web is just one of many output targets it supports.
To tap into its full power you need to author in a markup that predates Markdown called reStructuredText (reST). It's very similar to Markdown (MD) so it's never bothered me, but I know some people get very annoyed at the "uncanny valley" between reST and MD. reST has some very powerful yet simple features; it perplexes me that these aren't adopted in other docs systems. For example, to cross-link you just do :ref:`target` where `target` is an ID for a section. At "compile-time" the ref is replaced with the section title text. If you remove that ID then the build fails. Always accurate internal links, in other words.
The extension system really works and there is quite a large ecosystem of extensions on PyPI for common tasks, such as generating a sitemap.
The documentation for Sphinx is ironically not great; not terrible but not great either. I eventually accomplish whatever I need to do but the sub-optimal docs make the research take a bit longer than it probably has to.
I have been a technical writer for 11 years and have used many SSGs over the years. There's no perfect SSG but Sphinx strikes the best balance between the common tradeoffs.
[1] https://www.sphinx-doc.org/en/master/index.html