Resources (``sphinx``)

[Mischback]

Extensions / Plugins

• [ ] https://pypi.org/search/?c=Framework+%3A%3A+Sphinx+%3A%3A+Extension
• [x] https://github.com/sphinx-contrib/sphinx-lint
  • a dedicated linter for sphinx, included in sphinx-contrib
  • existing hook for pre-commit
  • not sure of the advantages compared to doc8, just using both of them
• [ ] https://github.com/executablebooks/web-compile
  • NEEDS evaluation
  • provides SASS compilation, JS minification and hashing of files (might also provide Jinja2 template tags to automatically include the hashed file, which would basically provide cache-busting)
• [ ] https://github.com/executablebooks/sphinx-copybutton
  • adds a button to source code elements for easy copy/paste
  • NEEDS evaluation
  • most likely some arcane JS
• [ ] https://sphinxext-opengraph.readthedocs.io/en/latest/index.html
  • SEO
  • NEEDS evaluation
  • what is the benefit compared to just integrating this into the (custom) templates
• [ ] https://github.com/jdillard/sphinx-sitemap
  • generate the sitemap.xml
  • NEEDS evaluation
• [ ] https://sphinx-external-toc.readthedocs.io/en/latest/intro.html
  • manual TOCs
  • NEEDS evaluation
  • might be an alternative to using sitemap.rst as root_doc
• [x] https://sphinx-notfound-page.readthedocs.io/en/latest/index.html
  • NEEDS evaluation
• [ ] https://gitlab.com/documatt/sphinx-reredirects
  • might be more handy than managing a .htaccess file
• [ ] https://github.com/wpilibsuite/sphinxext-photofinish
  • great purpose
  • I don't know if I like the idea of generating the required images from the sphinx build process
  • might be a reference for a custom plugin/extension
• [x] https://github.com/sunpy/ablog
  • a weblog engine based on Sphinx
  • have a look at the PostDirective class for an implementation of dedicated meta information
  • Check how this meta information is processed / displayed

Guides / Articles

• https://sammart.in/post/2021-05-10-external-data-sphinx-extension/
• https://lornajane.net/posts/2021/define-navigation-structure-in-a-sphinx-project
• https://lornajane.net/posts/2021/sphinx-front-matter-and-template-variables
• https://github.com/sphinx-doc/sphinx/tree/master/sphinx/themes/basic
• https://github.com/reinout/reinout.vanrees.org

[Mischback]

Theming

• Sphinx's basic theme
• Theme development
• Templating
• Using/configuring HTML themes
• Jinja2
  • https://jinja.palletsprojects.com/en/3.0.x/templates/

[Mischback]

https://github.com/badges/awesome-badges