Just want to +1 this, and also add a twist. The Sphinx community also has a great extension called hieroglyph, which lets you use rST directives to build slide presentations which also double as single-page HTML notes documents.
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.
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.
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.