Sphinx Python Documentation Generator: Documentation
Georg Brandl
Computers & Technology
Sphinx Python Documentation Generator: Documentation
Free
Description
Contents
Reviews

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. Of course, this site is also created from reStructuredText sources using Sphinx! The following features should be highlighted:


  • Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), ePub, Texinfo, manual pages, plain text

  • Extensive cross-references: semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information

  • Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children

  • Automatic indices: general index as well as a language-specific module indices

  • Code handling: automatic highlighting using the Pygments highlighter

  • Extensions: automatic testing of code snippets, inclusion of docstrings from Python modules (API docs), and more

  • Contributed extensions: more than 50 extensions contributed by users in a second repository; most of them installable from PyPI

Read online at sphinx-doc.org

Language
English
ISBN
9784873116488
Navigation
Welcome
Documentation
Examples
Hosting
Contributor Guide
Navigation
Sphinx documentation contents
Indices and tables
Navigation
Introduction
Conversion from other systems
Use with other systems
Prerequisites
Usage
Navigation
First Steps with Sphinx
Install Sphinx
Setting up the documentation sources
Defining document structure
Adding content
Running the build
Documenting objects
Basic configuration
Autodoc
Intersphinx
More topics to be covered
Navigation
Invocation of sphinx-quickstart
Structure options
Project basic options
Extension options
Makefile and Batchfile creation options
Invocation of sphinx-build
Makefile options
Invocation of sphinx-apidoc
Navigation
reStructuredText Primer
Paragraphs
Inline markup
Lists and Quote-like blocks
Source Code
Tables
Hyperlinks
External links
Internal links
Sections
Explicit Markup
Directives
Images
Footnotes
Citations
Substitutions
Comments
Source encoding
Gotchas
Navigation
Sphinx Markup Constructs
Navigation
The TOC tree
Special names
Navigation
Paragraph-level markup
Table-of-contents markup
Glossary
Grammar production displays
Navigation
Showing code examples
Line numbers
Includes
Caption and name
Dedent
Navigation
Inline markup
Cross-referencing syntax
Cross-referencing anything
Cross-referencing objects
Cross-referencing arbitrary locations
Cross-referencing documents
Referencing downloadable files
Cross-referencing figures by figure number
Cross-referencing other items of interest
Other semantic markup
Substitutions
Navigation
Miscellaneous markup
File-wide metadata
Meta-information markup
Index-generating markup
Including content based on tags
Tables
Navigation
Sphinx Domains
What is a Domain?
Basic Markup
Cross-referencing syntax
The Python Domain
Python Signatures
Info field lists
Cross-referencing Python objects
The C Domain
Cross-referencing C constructs
The C++ Domain
Namespacing
Info field lists
Cross-referencing
The Standard Domain
The JavaScript Domain
The reStructuredText domain
More domains
Navigation
Available builders
Serialization builder details
Navigation
The build configuration file
General configuration
Project information
Options for internationalization
Options for HTML output
Options for Apple Help output
Options for epub output
Options for LaTeX output
Options for text output
Options for manual page output
Options for Texinfo output
Options for the linkcheck builder
Options for the XML builder
Navigation
Internationalization
Sphinx internationalization details
Translating with sphinx-intl
Quick guide
Translating
Update your po files by new pot files
Using Transifex service for team translation
Contributing to Sphinx reference translation
Navigation
HTML theming support
Using a theme
Builtin themes
Creating themes
Templating
Static templates
Navigation
Templating
Do I need to use Sphinx’s templates to produce HTML?
Jinja/Sphinx Templating Primer
Working with the builtin templates
Blocks
Configuration Variables
Helper Functions
Global Variables
Navigation
Sphinx Extensions
Builtin Sphinx extensions
Third-party extensions
Where to put your own extensions?
Navigation
sphinx.ext.autodoc – Include documentation from docstrings
Docstring preprocessing
Skipping members
Navigation
sphinx.ext.autosectionlabel – Allow reference sections using its title
Navigation
sphinx.ext.autosummary – Generate autodoc summaries
sphinx-autogen – generate autodoc stub pages
Generating stub pages automatically
Customizing templates
Navigation
sphinx.ext.coverage – Collect doc coverage stats
Navigation
sphinx.ext.doctest – Test snippets in the documentation
Directives
Configuration
Navigation
sphinx.ext.extlinks – Markup to shorten external links
Navigation
sphinx.ext.githubpages – Publish HTML docs in GitHub Pages
Navigation
sphinx.ext.graphviz – Add Graphviz graphs
Navigation
sphinx.ext.ifconfig – Include content based on configuration
Navigation
sphinx.ext.inheritance_diagram – Include inheritance diagrams
Navigation
sphinx.ext.intersphinx – Link to other projects’ documentation
Navigation
sphinx.ext.linkcode – Add external links to source code
Navigation
Math support in Sphinx
sphinx.ext.imgmath – Render math as images
sphinx.ext.mathjax – Render math via JavaScript
sphinx.ext.jsmath – Render math via JavaScript
Navigation
sphinx.ext.napoleon – Support for NumPy and Google style docstrings
Napoleon - Marching toward legible docstrings
Getting Started
Docstrings
Docstring Sections
Google vs NumPy
Configuration
Navigation
sphinx.ext.todo – Support for todo items
Navigation
sphinx.ext.viewcode – Add links to highlighted source code
Navigation
Developing extensions for Sphinx
Extension metadata
APIs used for writing extensions
Navigation
Tutorial: Writing a simple extension
Important objects
Build Phases
Extension Design
The Setup Function
The Node Classes
The Directive Classes
The Event Handlers
Navigation
Application API
Extension setup
Emitting events
Producing messages / logging
Sphinx core events
Checking the Sphinx version
The Config object
The template bridge
Exceptions
Navigation
Build environment API
Navigation
Builder API
Navigation
Docutils markup API
Roles
Directives
ViewLists
Parsing directive content as ReST
Navigation
Domain API
Navigation
Parser API
Navigation
Doctree node classes added by Sphinx
Nodes for domain-specific object descriptions
New admonition-like constructs
Other paragraph-level nodes
New inline nodes
Special nodes
Navigation
Sphinx Web Support
Navigation
Web Support Quick Start
Building Documentation Data
Integrating Sphinx Documents Into Your Webapp
Authentication
Performing Searches
Comments & Proposals
Comment Moderation
Navigation
The WebSupport Class
Methods
Navigation
Search Adapters
BaseSearch Methods
Navigation
Storage Backends
StorageBackend Methods
Navigation
Sphinx FAQ
How do I...
Using Sphinx with...
Epub info
Texinfo info
Displaying Links
Notes
Navigation
Glossary
Navigation
Sphinx Developer’s Guide
Bug Reports and Feature Requests
Contributing to Sphinx
Getting Started
Core Developers
Locale updates
Coding Guide
Debugging Tips
Navigation
Changes in Sphinx
Release 1.4.2 (in development)
Features added
Bugs fixed
Release 1.4.1 (released Apr 12, 2016)
Incompatible changes
Translations
Bugs fixed
Release 1.4 (released Mar 28, 2016)
Incompatible changes
Features added
Bugs fixed
Documentation
Release 1.3.6 (released Feb 29, 2016)
Features added
Bugs fixed
Release 1.3.5 (released Jan 24, 2016)
Bugs fixed
Release 1.3.4 (released Jan 12, 2016)
Bugs fixed
Release 1.3.3 (released Dec 2, 2015)
Bugs fixed
Release 1.3.2 (released Nov 29, 2015)
Features added
Bugs fixed
Release 1.3.1 (released Mar 17, 2015)
Bugs fixed
Release 1.3 (released Mar 10, 2015)
Incompatible changes
Features added
Bugs fixed
Documentation
Release 1.3b3 (released Feb 24, 2015)
Incompatible changes
Features added
Bugs fixed
Release 1.3b2 (released Dec 5, 2014)
Incompatible changes
Features added
Bugs fixed
Release 1.3b1 (released Oct 10, 2014)
Incompatible changes
Features added
Bugs fixed
Documentation
Release 1.2.3 (released Sep 1, 2014)
Features added
Bugs fixed
Release 1.2.2 (released Mar 2, 2014)
Bugs fixed
Documentation
Release 1.2.1 (released Jan 19, 2014)
Bugs fixed
Documentation
Release 1.2 (released Dec 10, 2013)
Features added
Incompatible changes
Bugs fixed
Release 1.2 beta3 (released Oct 3, 2013)
Features added
Incompatible changes
Bugs fixed
Release 1.2 beta2 (released Sep 17, 2013)
Features added
Incompatible changes
Bugs fixed
Release 1.2 beta1 (released Mar 31, 2013)
Incompatible changes
Features added
Documentation
Bugs fixed
Release 1.1.3 (Mar 10, 2012)
Release 1.1.2 (Nov 1, 2011) – 1.1.1 is a silly version number anyway!
Release 1.1.1 (Nov 1, 2011)
Release 1.1 (Oct 9, 2011)
Incompatible changes
Features added
Release 1.0.8 (Sep 23, 2011)
Release 1.0.7 (Jan 15, 2011)
Release 1.0.6 (Jan 04, 2011)
Release 1.0.5 (Nov 12, 2010)
Release 1.0.4 (Sep 17, 2010)
Release 1.0.3 (Aug 23, 2010)
Release 1.0.2 (Aug 14, 2010)
Release 1.0.1 (Jul 27, 2010)
Release 1.0 (Jul 23, 2010)
Incompatible changes
Features added
Previous versions
Navigation
Projects using Sphinx
Documentation using the alabaster theme
Documentation using the classic theme
Documentation using a customized version of the classic theme
Documentation using the sphinxdoc theme
Documentation using another builtin theme
Documentation using a custom theme/integrated in a site
Homepages and other non-documentation sites
Books produced using Sphinx
Thesis using Sphinx
Navigation
Sphinx authors
Navigation
Installing Sphinx
Debian/Ubuntu: Install Sphinx using packaging system
Other Linux distributions
Mac OS X: Install Sphinx using MacPorts
Windows: Install Python and Sphinx
Install Python
Install the pip command
Installing Sphinx with pip
Navigation
Sphinx development
Extensions
Python Module Index
Source code for docutils.parsers.rst
All modules for which code is available
Source code for sphinx.addnodes
Source code for sphinx.application
Source code for sphinx.builders
Source code for sphinx.builders.applehelp
Source code for sphinx.builders.changes
Source code for sphinx.builders.devhelp
Source code for sphinx.builders.dummy
Source code for sphinx.builders.epub
Source code for sphinx.builders.epub3
Source code for sphinx.builders.gettext
Source code for sphinx.builders.html
Source code for sphinx.builders.htmlhelp
Source code for sphinx.builders.latex
Source code for sphinx.builders.linkcheck
Source code for sphinx.builders.manpage
Source code for sphinx.builders.qthelp
Source code for sphinx.builders.texinfo
Source code for sphinx.builders.text
Source code for sphinx.builders.xml
Source code for sphinx.config
Source code for sphinx.domains
Source code for sphinx.environment
Source code for sphinx.errors
Source code for sphinx.ext.autodoc
Source code for sphinx.ext.coverage
Source code for sphinx.parsers
Source code for sphinx.websupport
Source code for sphinx.websupport.search
Source code for sphinx.websupport.storage
Example Google Style Python Docstrings
Example NumPy Style Python Docstrings
sphinx-apidoc manual page
sphinx-build manual page
sphinx-quickstart manual page
The book hasn't received reviews yet.