Dump notes from Sphinx unconference

[astrojuanlu]

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!

[plaindocs]

Hey @astrojuanlu

I totally missed this ping, sorry!

I'd throw it in here as a session report or something https://www.writethedocs.org/guide/tools/sphinx/