Sphinx

When created for the first time, it's main purpose was to serve as a documentation generator for Python's own code.

Since then, the project has reached cult status in the development world, being one of the most referenced influences in most automatic documentation generators around, regardless of language.

Today, besides just Python, Sphinx can also be used with C and C++ code as well.

What is new in this release:

• Add convenience directives and roles to the C++ domain: directive ``cpp:var`` as alias for ``cpp:member``, role ``:cpp:var`` as alias for ``:cpp:member``, and role `any` for cross-reference to any C++ declaraction.
• The :confval:`source_suffix` config value can now be a list of multiple suffixes.
• Add the ability to specify source parsers by source suffix with the :confval:`source_parsers` config value.
• A new builder, AppleHelpBuilder, has been added that builds Apple Help Books.

What is new in version 1.2.3 / 1.3b3:

• Added ``sphinx.version_info`` tuple for programmatic checking of the Sphinx version.

What is new in version 1.1.3:

• Fixed crash with some settings of :confval:`modindex_common_prefix`.
• Fixed handling of ``-D`` and ``-A`` options on Python 3.
• Recognized and warn about circular toctrees, instead of running into recursion errors.
• Restore compatibility with docutils trunk.
• Fixed HtmlHelp index entry links again.
• Fixed inheritance_diagram raising attribute errors on builtins.
• Fixed crashes when putting comments or lone terms in a glossary.
• Fixed HTML help language/encoding mapping for all Sphinx supported languages.

What is new in version 1.1:

• Features added:
• Added Python 3.x support.
• New builders and subsystem.
• Incompatible changes:
• The :rst:dir:`py:module` directive doesn't output its ``platform`` option value anymore. (It was the only thing that the directive did output, and therefore quite inconsistent.)
• Removed support for old dependency versions.
• New locales:
• Added Swedish locale.
• Added Iranian locale.
• Added Latvian locale.
• Added Nepali locale.
• Added Korean locale.
• Added Estonian locale.

What is new in version 1.0.8:

• Fix tracebacks for AttributeErrors in autosummary generation.
• Fix the ``abbr`` role when the abbreviation has newlines in it.
• Fix the links to search results with custom object types.
• Fix line numbers reported in warnings about undefined references.
• Fix C++ array definitions and template arguments that are not type names.
• Allow footnotes in section headers in LaTeX output.
• Allow keywords to be linked via intersphinx.
• Allow Unicode characters in production list token names.
• Add dummy visitors for graphviz nodes for text and man.
• Fix image file duplication bug.
• Fix parsing of multiple signatures in C++ domain.
• Ignore Emacs lock files when looking for source files.
• Allow .pyw extension for importable modules in autodoc.
• Use ``$(MAKE)`` in quickstart-generated Makefiles.
• Make sidebar search box width consistent in browsers.
• Fix spacing of centered figures in HTML output.
• Safely encode SphinxError messages when printing them to sys.stderr.
• Fix LaTeX output error with a document with no sections but a link target.
• Correctly treat built-in method descriptors as methods in autodoc.
• Stop monkeypatching the Python textwrap module.
• Viewcode now works correctly with source files that have non-ASCII encoding.
• Respect the ``noindex`` flag option in py:module directives.
• Fix IndexErrors when including nonexisting lines with :rst:dir:`literalinclude`.
• Respect custom function/method parameter separator strings.
• Fix JS incompatibility with jQuery >= 1.5.
• Fix double encoding done when writing HTMLHelp .hhk files.
• Do not apply SmartyPants in parsed-literal blocks.
• C++ domain now supports array definitions.

What is new in version 1.0.6:

• Fix traceback in Python domain for empty cross-reference targets.
• Fix literal block display issues on Chrome browsers.
• Support sorting a limited range of accented characters in the general index and the glossary.
• Try decoding ``-D`` and ``-A`` command-line arguments with the locale's preferred encoding.
• Observe :confval:`locale_dirs` when looking for the JS translations file.
• Add special code for better support of Japanese documents in the LaTeX builder.
• Regression of #77: If there is only one parameter given with ``:param:`` markup, the bullet list is now suppressed again.
• Fix missing paragraph breaks in LaTeX output in certain situations.
• Emit the ``autodoc-process-docstring`` event even for objects without a docstring so that it can add content.
• In the LaTeX builder, not only literal blocks require different table handling, but also quite a few other list-like block elements.
• Fix tracebacks in the viewcode extension for Python objects that do not have a valid signature.
• Fix strange reportings of line numbers for warnings generated from autodoc-included docstrings, due to different behavior depending on docutils version.
• Several fixes to the C++ domain.

What is new in version 1.0.5:

• Add CSS styles required by docutils 0.7 for aligned images and figures.
• In the Makefile generated by LaTeX output, do not delete pdf files on clean; they might be required images.
• Fix LaTeX output generated for line blocks.
• Allow ``.pyw`` as a source file extension.

What is new in version 1.0.4:

• Open intersphinx inventories in binary mode on Windows, since version 2 contains zlib-compressed data.
• Allow giving non-local URIs for JavaScript files, e.g. in the JSMath extension.
• Fix traceback when ``intersphinx_mapping`` is empty.

What is new in version 1.0.3:

• Fix internal vs. external link distinction for links coming from a docutils table-of-contents.
• Fix the ``maxdepth`` option for the ``toctree()`` template callable when used with ``collapse=True``.
• Fix crash parsing Python argument lists containing brackets in string literals.
• Fix regression when building LaTeX docs with figures that don't have captions.
• Fix inheritance diagrams for classes that are not picklable.
• Introduce separate background color for the sidebar collapse button, making it easier to see.
• Fix small layout bugs in several built-in themes.

What is new in version 1.0.2:

• Fix cross-references to objects of types added by the :func:`~.Sphinx.add_object_type` API function.
• Fix handling of doc field types for different directive types.
• Allow breaking long signatures, continuing with backlash-escaped newlines.
• Fix unwanted styling of C domain references (because of a namespace clash with Pygments styles).
• Allow references to PEPs and RFCs with explicit anchors.
• Fix LaTeX references to figures.
• When doing a non-exact search, match only the given type of object.
• Apply non-exact search for Python reference targets with ``.name`` for modules too.
• Fix crash when duplicating a parameter in an info field list.
• Fix setting the default role to one provided by the ``oldcmarkup`` extension.
• Fix crash when json-py is installed, which provides a ``json`` module but is incompatible to simplejson.
• Fix handling of target naming in intersphinx.
• Fix removal of ``!`` for all cross-reference roles.

What is new in version 1.0.1:

• Fix generated target names for reST domain objects; they are not in the same namespace.
• Add Bengali language.
• Fix a bug in parsing JavaScript object names.
• Fix building with SingleHTMLBuilder when there is no toctree.
• Fix display names for objects linked to by intersphinx with explicit targets.
• Fix building with the JSON builder.
• Fix hyperrefs in object descriptions for LaTeX.

What is new in version 1.0:

• General:
• Added a "nitpicky" mode that emits warnings for all missing references. It is activated by the :option:`-n` command-line switch or the :confval:`nitpicky` config value.
• Added ``latexpdf`` target in quickstart Makefile.
• Markup:
• The :rst:role:`menuselection` and :rst:role:`guilabel` roles now support ampersand accelerators.
• New more compact doc field syntax is now recognized: ``:param type name: description``.
• Added ``tab-width`` option to :rst:dir:`literalinclude` directive.
• Added ``titlesonly`` option to :rst:dir:`toctree` directive.
• Added the ``prepend`` and ``append`` options to the :rst:dir:`literalinclude` directive.
• All docinfo metadata is now put into the document metadata, not just the author.
• The :rst:role:`ref` role can now also reference tables by caption.
• The :rst:dir:`include` directive now supports absolute paths, which are interpreted as relative to the source directory.
• In the Python domain, references like ``:func:`.name``` now look for matching names with any prefix if no direct match is found.
• Configuration:
• Added :confval:`rst_prolog` config value.
• Added :confval:`html_secnumber_suffix` config value to control section numbering format.
• Added :confval:`html_compact_lists` config value to control docutils' compact lists feature.
• The :confval:`html_sidebars` config value can now contain patterns as keys, and the values can be lists that explicitly select which sidebar templates should be rendered. That means that the builtin sidebar contents can be included only selectively.
• :confval:`html_static_path` can now contain single file entries.
• The new universal config value :confval:`exclude_patterns` makes the old :confval:`unused_docs`, :confval:`exclude_trees` and :confval:`exclude_dirnames` obsolete.
• Added :confval:`html_output_encoding` config value.
• Added the :confval:`latex_docclass` config value and made the "twoside" documentclass option overridable by "oneside".
• Added the :confval:`trim_doctest_flags` config value, which is true by default.
• Added :confval:`html_show_copyright` config value.
• Added :confval:`latex_show_pagerefs` and :confval:`latex_show_urls` config values.
• The behavior of :confval:`html_file_suffix` changed slightly: the empty string now means "no suffix" instead of "default suffix", use ``None`` for "default suffix".
• New builders:
• Added a builder for the Epub format.
• Added a builder for manual pages.
• Added a single-file HTML builder.
• HTML output:
• Inline roles now get a CSS class with their name, allowing styles to customize their appearance. Domain-specific roles get two classes, ``domain`` and ``domain-rolename``.
• References now get the class ``internal`` if they are internal to the whole project, as opposed to internal to the current page.
• External references can be styled differently with the new ``externalrefs`` theme option for the default theme.
• In the default theme, the sidebar can experimentally now be made collapsible using the new ``collapsiblesidebar`` theme option.
• Toctrees are now wrapped in a ``div`` tag with class ``toctree-wrapper`` in HTML output.
• The :data:`toctree` callable in templates now has a ``maxdepth`` keyword argument to control the depth of the generated tree.
• The :data:`toctree` callable in templates now accepts a ``titles_only`` keyword argument.
• Added ``htmltitle`` block in layout template.
• In the JavaScript search, allow searching for object names including the module name, like ``sys.argv``.
• Added new theme ``haiku``, inspired by the Haiku OS user guide.
• Added new theme ``nature``.
• Added new theme ``agogo``, created by Andi Albrecht.
• Added new theme ``scrolls``, created by Armin Ronacher.
• Added a ``visitedlinkcolor`` theme option to the default theme.
• Improved responsiveness of the search page by loading thesearch index asynchronously.
• Extension API:
• Added :event:`html-collect-pages`.
• Added :confval:`needs_sphinx` config value and :meth:`~sphinx.application.Sphinx.require_sphinx` application API method.
• Added :meth:`~sphinx.application.Sphinx.add_stylesheet` application API method.
• Extensions:
• Added the :mod:`~sphinx.ext.viewcode` extension.
• Added the :mod:`~sphinx.ext.extlinks` extension.
• Added support for source ordering of members in autodoc, with ``autodoc_member_order = 'bysource'``.
• Added :confval:`autodoc_default_flags` config value, which can be used to select default flags for all autodoc directives.
• Added a way for intersphinx to refer to named labels in other projects, and to specify the project you want to link to.
• Autodoc can now document instance attributes assigned in ``__init__`` methods.
• Many improvements and fixes to the :mod:`~sphinx.ext.autosummary` extension, thanks to Pauli Virtanen.
• The :mod:`~sphinx.ext.graphviz` extension can now output SVG instead of PNG images, controlled by the confval:`graphviz_output_format` config value.
• Added ``alt`` option to :rst:dir:`graphviz` extension directives.
• Added ``exclude`` argument to :func:`.autodoc.between`.
• Translations:
• Added Croatian translation, thanks to Bojan Mihelac.
• Added Turkish translation, thanks to Firat Ozgul.
• Added Catalan translation, thanks to Pau Fernandez.
• Added simplified Chinese translation.
• Added Danish translation, thanks to Hjorth Larsen.
• Added Lithuanian translation, thanks to Dalius Dobravolskas.

What is new in version 1.0b1:

• Support for domains has been added. A domain is a collection of directives and roles that all describe objects belonging together, e.g. elements of a programming language. A few builtin domains are provided: - Python - C - C++ - JavaScript - reStructuredText
• The old markup for defining and linking to C directives will not work anymore without activating the ``oldcmarkup`` extension.
• Removed support for old dependency versions.
• Removed deprecated elements.

What is new in version 0.6.5:

• In autodoc, fix the omission of some module members explicitly documented using documentation comments.
• Fix cropping of sidebar scroll bar with ``stickysidebar`` option of the default theme.
• Always generate UNIX newlines in the quickstart Makefile.
• Fix running with ``-C`` under Windows.
• In autodoc, allow customizing the signature of an object where the built-in mechanism fails.
• Fix output for enumerated lists with start values in LaTeX.
• Make the ``start-after`` and ``end-before`` options to the ``literalinclude`` directive work correctly if not used together.
• Fix link generation in the LaTeX builder.

What is new in version 0.6.4:

• Improved the handling of non-Unicode strings in the configuration.
• Catch OSErrors occurring when calling graphviz with arguments it doesn't understand.
• Restore compatibility with Pygments >= 1.2.
• Fix escaping of hyperref targets in LaTeX output.
• Fix links generated by the ``:doc:`` role for LaTeX output.
• Collect todo nodes after the whole document has been read; this allows placing substitution references in todo items.
• Do not ignore an explicit ``today`` config value in a LaTeX build.
• The ``alt`` text of inheritance diagrams is now much cleaner.
• Ignore images in section titles when generating link captions.
• Support exception messages in the ``testoutput`` blocks of the ``doctest`` extension.
• Line blocks are styled properly in HTML output.
• Made the ``locale_dirs`` config value work again.
• ``html_context`` values given on the command line via ``-A`` should not override other values given in conf.py.
• Fix a bug preventing incremental rebuilds for the ``dirhtml`` builder.
• Fix the mangling of quotes in some literal blocks.
• Fix path to the search index for the ``dirhtml`` builder.
• Fix a Jython compatibility issue: make the dependence on the ``parser`` module optional.
• In autodoc, catch all errors that occur on module import, not just ``ImportError``.
• Fix the handling of non-data, but non-method descriptors in autodoc.
• When copying file times, ignore OSErrors raised by ``os.utime()``.

Requirements:

• Pygments 1.2 or higher
• Jinja 2.3 or higher
• Docutils 0/7 or higher