Dump notes from Sphinx unconference #1516
Description
Raw, almost unedited notes from our unconference session on Sphinx. Suggestion by @plaindocs - what do you think would be the best place to put these?
- what do you love about sphinx
- code introspection
- "docs as code" mindset (x2)
- searchable, integrated with my source code
- reStructuredText, more powerful than Markdown (x3)
- "you have to push it quite hard to find gaps"
- intersphinx (cross linking to external documentation sets!) https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
- allows building docs as several interconnected projects
- domains: Python, C, C++, JavaScript, reST (and there's a MATLAB extension as well https://pypi.org/project/sphinxcontrib-matlabdomain/)
- what do you dislike
- navigation, creation of tables of contents
- its documentation! very geared towards people looking for a reference, not for learners
- "99 % I look up syntax of things"
- I've been feeling so stupid reading those docs...
- "I would have LOVED a real Hello World exercise"
- markdown in sphinx
- "we receive contributions either in markdown or reST, sphinx handles both simultaneously"
- recommonmark is going to be deprecated, and the community is encouraged to move to MyST https://myst-parser.readthedocs.io/en/latest/
- sphinx is unfortunately a big barrier of entry, what good materials are out there?
- @juanlu is tasked with writing a Sphinx tutorial, will open an issue upstream soon!
- https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html
- https://dont-be-afraid-to-commit.readthedocs.io/en/latest/
- what's the momentum of Sphinx and reStructuredText in the industry?
- "I worry about asciidoc: it's a one-man show"
- Sphinx is basically maintained by two people during the weekends
- the Jamstack philosophy is gaining momentum (Gatsby, Hugo, etc)
- how to convince developers to move from an existing documentation system (Doxygen, for example) to Sphinx?
- one nice feature: having both API and narrative docs
- "it's common to have different teams use different documentation systems"
- what do people think about themes?
- furo
- "we grabbed rtd theme and never thought about it again"
- "theming in Sphinx is... obscure"
- some scientific projects are moving to pydata-sphinx-theme
- https://sphinx-theme.scylladb.com/stable/contribute/contribute-docs.html (and ScyllaDB is designing another theme to be published soon)
- how scary is it to upgrade it?
- "we are using 1.8 because we don't want to break everything"
- "I've never seen it break"
- "the extension API does change though"
- conclusion: sphinx rocks!