RSS

Sphinx documentation builder

• https://github.com/sphinx-doc/sphinx

• https://github.com/sphinx-doc/sphinx/graphs/contributors

• http://www.sphinx-doc.org/en/master/

• https://en.wikipedia.org/wiki/Sphinx_(documentation_generator )

• https://pradyunsg.me/furo/reference/

• http://rest-sphinx-memo.readthedocs.org/en/latest/Project.html

• http://rest-sphinx-memo.readthedocs.org/en/latest/References.html

• http://redaction-technique.org/index.html

• https://github.com/sphinx-doc/sphinx/graphs/contributors

Sphinx logo

• http://blog.smartbear.com/software-quality/bid/256072/13-reasons-your-open-source-docs-make-people-want-to-scream

• http://brikis98.blogspot.de/2014/05/you-are-what-you-document.html

• http://redaction-technique.org/index.html

Our favorite document generator is sphinx and we use the reStructuredText markup and sphinx-design

I’m not impressed if you’re a good engineer. I’m impressed if you’re a good teammate.

https://fediverse.org/RandallKanna/status/1387202807103574016?s=20

Description

Sphinx is a tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD license.

It was originally created for the new Python documentation, and it has excellent facilities for the documentation of Python projects, but C/C++ is already supported as well, and it is planned to add special support for other languages as well.

Sphinx source code (Sphinx dev guide)

• https://github.com/sphinx-doc/sphinx

• Sphinx development (Development Guide)

Sphinx applications

• sphinx applications
  • Editing sphinx doc on the web
    • Baow
    • Github Fork and Edit button
    • pydocweb
    • copypasta and sphinx
      • garlicsims and copypasta
  • Sphinx to github
  • sphinx-wiki
    • Examples
  • sphinx tinkerer application
    • What is Tinkerer ?
    • Why Tinkerer ?
    • Hosting on bitbucket
    • Versions
      • tinkerer versions

Sphinx extensions (sphinx.ext.*)

• sphinx.ext. Sphinx extensions
  • sphinx.ext.autodoc
    • Description
    • Examples
  • sphinx.ext.autodoc.typehints ( autodoc_typehints ) (since sphinx 2.4.0, 2020-02-09)
    • Generating documents from type annotations
    • autodoc_typehints
  • sphinx.ext.autosummary (Generate autodoc summaries)
    • Generating stub pages automatically
  • sphinx.ext.intersphinx link to other projects documentation ! (the killer feature !)
    • Example : reference in tuto_docker
    • Example for this documentation:
    • Include HTML in generated Sphinx docs
      • conf.py
      • generate_javaapi_inv.py
      • index.html
      • index.txt
    • objects.inv
  • sphinx.ext.napoleon (Support for NumPy and Google style docstrings)
    • Description
    • Getting Started
    • Docstrings
    • Docstring Sections
    • Google vs NumPy
    • News 2020

Sphinx contributed extensions

• Contributed sphinx extensions
  • Blockdiag (simple diagram images generator)
    • Introduction
    • blockdiag pycon-japan-retrospective
  • Doxygen contributed extensions
    • doxygen installation on GNU/Linux
      • Prerequisite
      • Install in /opt/doxygen/1.7.2
      • Make the link to the current doxygen version
    • Breathe sphinx extension
      • Description
      • Gammu breathe example
    • Doxylink
      • Description
      • Doxylink Examples
    • integrate doxygen documentation in sphinx
      • Create 2 directories for sphinx and doxygen
      • Copy the doxygen output files in _build/html/_downloads directory
      • Download the index.html source file from sphinx documents
      • Tree docs directory
    • MIT rst tools
      • How to deploy the Doxygen output in Sphinx project
      • Pre-requisites
      • Part A:
      • Part B: Bridge to Doxygen HTML output
    • Robin : bridge between doxygen (XML) and sphinx via mongodb
      • Robin
      • Features
      • Prerequisites
      • Getting started
      • Status
  • javasphinx extension
  • LinuxDoc Sphinx-doc extensions for sophisticated C developer (NEW, 2016-07)
    • Introduction
    • Installation
    • Flat table
  • sphinx odt2sphinx extension
  • rstspreadsheet sphinx extension
  • rst2qhc (Qt)
  • sphinx-autoapi A new approach to API documentation in Sphinx
    • Description
    • Autoapi setup
    • Basics
    • Setting up jinja templates
    • Issues
      • sphinx-autoapi issues
    • Customization of sphinx-api by Antoine Beyeler with jinja templates
      • Generating beautiful Python API documentation with Sphinx AutoAPI and Jinja (a template engine) by Antoine Beyeler
  • sphinx-design A sphinx extension for designing beautiful, screen-size responsive web components
    • Referenced by
    • Migrating from sphinx-panels
    • Notable changes
    • Improved CSS
    • widgets
      • Article-info
      • Badges-button
      • Cards
      • div text
      • dropdown
      • Grids
      • icon
      • tab
      • versions
  • sphinx_inline_tabs Add inline tabbed content to your Sphinx documentation
    • Introduction
    • Installation
    • Features
    • Contributing
  • Sphinx comments hypothes.is interaction layer with Sphinx
    • Add comments and annotation functionality to your Sphinx website
      • Example
    • Repository structure
  • Sphinx-hoverxref Tooltip with content embedded when hover an internal reference (readthedocs only)
    • Announce
    • Description
    • Usage
    • Demo
  • sphinx-multiversion
    • Introduction
    • Quick start
      • Quick start
    • Article
  • sphinx report
    • Introduction
  • sphinx-js : autodoc-style extraction into Sphinx for your JS project
    • Why ?
    • Setup
  • sphinx UML extensions
    • Sphinx plantum extension
      • Usage
    • Sphinx pyreverse extension
      • Presentation
      • Install
      • Usage
      • Requires pyreverse from pylint
  • sphinx-gallery (Sphinx extension for automatic generation of an example gallery)
    • sphinx-gallery versions
      • sphinx-gallery 0.7.0 (2020-05-21)
  • sphinxcontrib-dashbuilder
    • Description
    • Zeal
  • Sphinx excel table
    • Description
  • sphinxcontrib-datatemplates
    • Introduction
    • Installation

Sphinx howto

• Sphinx howto
  • How to exclude some files or directories ?
• Sphinx for APIs (TOC entry for every function, class, and method)
  • Scanpy
    • scanpy
  • Sphinx for APIs autodocsumm
    • autodocsumm
  • TrojanZoo
    • TrojanZoo

Sphinx deployment

• Sphinx deployment
  • Articles
    • 2019
      • Document your project adding Sphinx to docker-compose.yml

Sphinx examples

• Projects using Sphinx
  • Very nice doc
    • The Atomic Simulation Environment (ASE)
      • Introduction
      • Source documentation
    • Buildout
    • Sphinx neuronvisio documentation
      • Source documentation
    • Passlib (very nice cloud_sptheme)
      • Source documentation
    • Sfepy
      • Source documentation
    • tortoise-orm
      • Fichier config.py
  • C++ doc (with doxylink, breathe, …)
    • Sphinx C++ examples
      • Doxylink examples
  • Nice doc
    • Askbot
    • Bottle.py
    • Python USB API for Canon digital cameras
    • Ceph
      • Announce
    • Django
      • How the Django documentation works
    • Exquires
      • Introduction
    • Dpm
    • Eyesopen
    • Sphinx gammu documentation
      • Gammu sphinx documentation
      • Other document
    • github2 using sphinx
      • Example
    • Macaron: Python O/R Mapper
    • Mediagobelin
    • Parcel (html_theme = “flask”)
      • Source documentation
    • Pylons
    • PysSCes
    • Python GTK+ 3 Tutorial
    • Python
      • python py3k
      • python dev
    • Sphinx Prody documentation
      • Source documentation
    • Requests
    • Simpy Documentation
    • sunpy Documentation
    • Sphinx
      • Description
      • Source documentation
    • SQLAlchemy 0.7 Documentation
    • Urwid Documentation
  • Classic doc
    • Tuleap
      • Announce
  • Non python projects
    • linux kernel
      • Introduction
      • Sphinx-doc extensions for sophisticated C developer

Sphinx i18n

• Sphinx i18n

Sphinx builders

• Sphinx builders
  • Sphinx LateX builders
    • LaTeXBuilder
      • Issues
    • MiKTeX installation
      • Dockerized MiKTeX
      • docker-sphinx

Sphinx installation

• Installation d’un projet sphinx
  • Installation d’une documentation Sphinx “reStructuredText” sous Windows
  • Production de la documentation html
  • Exemples d’installation
    • Exemples d’Installation d’un projet sphinx
      • Exemples d’Installation d’un projet sphinx 2.0.0

Sphinx objects.inv (inventory)

• objects.inv
  • Calling examples
  • sphinx.ext.intersphinx documentation #6911
  • Other examples

Sphinx usage

• Sphinx usage
  • Sphinx usage markdown (=> use MyST**)
    • 2021-05-05
  • Sphinx usage notebook
    • Practical sphinx
      • Jupyter/notebook

Sphinx tutorials

• Sphinx tutorials
  • sphinx-material
  • Rest Sphinx
  • Python
  • matplotlib
  • Plone
    • Github Fork and Edit button
  • Geoserver
  • Documentation style guide sphinx
  • Documentation style guide mercurial

Tools for Sphinx

• Tools for building sphinx
  • Qt program
    • Ironpython
    • Mac OS X
  • Automatically-build-sphinx-documentation
  • Rst lint

Sphinx themes

• Sphinx themes
  • sphinx furo theme
    • Useb by
  • sphinx-immaterial : Adaptation of the popular mkdocs-material material design theme to the sphinx documentation system by Jeremy Maitin-Shepard
    • Used by
  • sphinx-material : A material-based, responsive theme inspired by mkdocs-material by Kevin Sheppard
    • Discovery
    • Used by
      • sphinx-material
      • statsmodels
      • arch
      • paperless-ngx
      • tuto_sphinx_material
  • pydata-sphinx-theme (very good, A clean, three-column Sphinx theme with Bootstrap for the PyData community )
    • Gallery
      • predictablynoisy
      • geopandas
  • sphinx_book_theme
    • Used by
      • Tuto documentation
    • Installation
  • shibuya by Hsiaoming Yang (lepture)
    • Used by
      • authlib
      • jose (2023-06)

Sphinx templating

• Sphinx templating
  • Add javascript files
  • Creating themes
  • CSS and roles
    • sphinx CSS and custom-interpreted-text-roles
      • role:: underlined
      • Tip: vertical text
      • default.css file
  • Tips
    • Sphinx templating tips
      • Custom title page

Sphinx translations

• Sphinx translations
  • Announce

Sphinx versions

• Sphinx versions
  • Sphinx 7.3.5 (2024-04-17)
  • Sphinx 7.3.0 (2024-04-17)
    • Dependencies
    • Features added
      • Support theme configuration via theme.toml files
      • HTML Search: Adopt the new <search> element
      • Add long option names to sphinx-build (Improve usability of sphinx-build)
      • Add a versionremoved directive
      • Change the text of the versionadded directive from New in […] to Added in […]
      • Added show_warning_types configuration option
      • Other
  • Sphinx 7.0.0 (2023-04-29)
  • Sphinx 6.0.0 (2022-12-29)
    • Dependencies
  • Sphinx 5.1.0 (2022-07-24)
    • Dependencies
    • Deprecated
    • Features added
  • Sphinx 5.0.0 (2022-06-16)
    • Release 5.0.0 beta1 (released May 09, 2022)
      • Dependencies
      • Incompatible changes
      • Features added
  • Sphinx 4.2.0 (DEV)
  • Sphinx 4.1.2 (2021-07-26)
  • Sphinx 4.1.0 (2021-07-11)
  • Sphinx 4.0.0 (2021-05-09)
  • Sphinx 3.4.0 (2020-12-02)
  • Sphinx 3.3.0 (2020-11-02)
    • Deprecated
    • Features added
    • Bugs fixed
    • Testing
  • Sphinx 3.2.1 (2020-08-14)
    • Features added
    • Bugs fixed
  • Sphinx 3.0.0 (2020-04-06)
  • Sphinx 2.4.0 (2020-02-09) new features (typing) of sphinx.ext.autodoc in sphinx
    • New features of sphinx.ext.autodoc (typing) in sphinx 2.4.0
      • Support type annotations for variables
    • Show type annotations as its description (experimental)
      • signature mode
      • none mode
      • description mode (new!)
    • New extension sphinx.ext.autodoc.typehints
    • Features added
  • Sphinx 2.3.0 (2019-12-15)
  • Sphinx 2.2.0 (2019-08-19)
    • Incompatible changes
    • Deprecated
    • Features added
    • Bugs fixed
  • Sphinx 2.1.0 (2019-06-02)
    • Features added
  • Sphinx 2.0.0 (2019-03-28)
    • Dependencies
    • Incompatible changes
    • Features added
  • Sphinx 1.6.3 (2017-07-02)
    • Features added
    • Bugs fixed
  • Sphinx 1.2.3 (2014-09-01)
  • Release 1.1.1 (Nov 1, 2011)
  • Release 1.1 (Oct 9, 2011)
    • Incompatible changes
    • Features added