diff options
Diffstat (limited to 'doc')
74 files changed, 1828 insertions, 333 deletions
diff --git a/doc/_static/bookcover.png b/doc/_static/bookcover.png Binary files differindex 1c91f91f..5b521b67 100644 --- a/doc/_static/bookcover.png +++ b/doc/_static/bookcover.png diff --git a/doc/_static/pocoo.png b/doc/_static/pocoo.png Binary files differindex eeb18eaf..67663b97 100644 --- a/doc/_static/pocoo.png +++ b/doc/_static/pocoo.png diff --git a/doc/_static/sphinx.png b/doc/_static/sphinx.png Binary files differindex a4a3e1af..4bd9c753 100644 --- a/doc/_static/sphinx.png +++ b/doc/_static/sphinx.png diff --git a/doc/_templates/index.html b/doc/_templates/index.html index e6ef9178..2016ea9f 100644 --- a/doc/_templates/index.html +++ b/doc/_templates/index.html @@ -34,6 +34,9 @@ <li>{%trans path=pathto('extensions')%}<b>Extensions:</b> automatic testing of code snippets, inclusion of docstrings from Python modules (API docs), and <a href="{{ path }}#builtin-sphinx-extensions">more</a>{%endtrans%}</li> + <li>{%trans path=pathto('develop')%}<b>Contributed extensions:</b> more than + 50 extensions <a href="{{ path }}#extensions">contributed by users</a> + in a second repository; most of them installable from PyPI{%endtrans%}</li> </ul> <p>{%trans%} Sphinx uses <a href="http://docutils.sf.net/rst.html">reStructuredText</a> @@ -97,4 +100,14 @@ powerful built-in search that exceeds the possibilities of Sphinx' JavaScript-based offline search.{%endtrans%}</p> + <h2>{%trans%}Contributor Guide{%endtrans%}</h2> + + <p>{%trans%}If you want to contribute to the project, + this part of the documentation is for you.{%endtrans%}</p> + + <ul> + <li>{%trans path=pathto("devguide")%}<a href="{{ path }}">Sphinx Developer’s Guide</a></li>{%endtrans%} + <li>{%trans path=pathto("authors")%}<a href="{{ path }}">Sphinx Authors</a></li>{%endtrans%} + </ul> + {% endblock %} diff --git a/doc/_templates/indexsidebar.html b/doc/_templates/indexsidebar.html index 4a350ae4..db925c88 100644 --- a/doc/_templates/indexsidebar.html +++ b/doc/_templates/indexsidebar.html @@ -3,7 +3,7 @@ {%trans%}project{%endtrans%}</p> <h3>Download</h3> -{% if version.endswith('(hg)') %} +{% if version.endswith('a0') %} <p>{%trans%}This documentation is for version <b>{{ version }}</b>, which is not released yet.{%endtrans%}</p> <p>{%trans%}You can use it from the @@ -14,7 +14,7 @@ <p>{%trans%}Current version: <b>{{ version }}</b>{%endtrans%}</p> <p>{%trans%}Get Sphinx from the <a href="http://pypi.python.org/pypi/Sphinx">Python Package Index</a>, or install it with:{%endtrans%}</p> -<pre>easy_install -U Sphinx</pre> +<pre>pip install -U Sphinx</pre> <p>{%trans%}Latest <a href="http://sphinx-doc.org/latest/">development version docs</a> are also available.{%endtrans%}</p> {% endif %} diff --git a/doc/_themes/sphinx13/static/bodybg.png b/doc/_themes/sphinx13/static/bodybg.png Binary files differindex 506b6f90..ebe92f66 100644 --- a/doc/_themes/sphinx13/static/bodybg.png +++ b/doc/_themes/sphinx13/static/bodybg.png diff --git a/doc/_themes/sphinx13/static/footerbg.png b/doc/_themes/sphinx13/static/footerbg.png Binary files differindex d1922b44..df783e2c 100644 --- a/doc/_themes/sphinx13/static/footerbg.png +++ b/doc/_themes/sphinx13/static/footerbg.png diff --git a/doc/_themes/sphinx13/static/headerbg.png b/doc/_themes/sphinx13/static/headerbg.png Binary files differindex 6d3e1d5e..22830f99 100644 --- a/doc/_themes/sphinx13/static/headerbg.png +++ b/doc/_themes/sphinx13/static/headerbg.png diff --git a/doc/_themes/sphinx13/static/relbg.png b/doc/_themes/sphinx13/static/relbg.png Binary files differindex 47225851..2006af7d 100644 --- a/doc/_themes/sphinx13/static/relbg.png +++ b/doc/_themes/sphinx13/static/relbg.png diff --git a/doc/_themes/sphinx13/static/sphinxheader.png b/doc/_themes/sphinx13/static/sphinxheader.png Binary files differindex 2b33f09d..12988c3d 100644 --- a/doc/_themes/sphinx13/static/sphinxheader.png +++ b/doc/_themes/sphinx13/static/sphinxheader.png diff --git a/doc/authors.rst b/doc/authors.rst new file mode 100644 index 00000000..980b33e8 --- /dev/null +++ b/doc/authors.rst @@ -0,0 +1,9 @@ +:tocdepth: 2 + +.. _authors: + +Sphinx authors +============== + +.. include:: ../AUTHORS + diff --git a/doc/builders.rst b/doc/builders.rst index 333750e0..3c6f6b98 100644 --- a/doc/builders.rst +++ b/doc/builders.rst @@ -153,11 +153,6 @@ for details. .. autoattribute:: supported_image_types - .. note:: - - This builder requires the docutils manual page writer, which is only - available as of docutils 0.6. - .. versionadded:: 1.0 @@ -282,8 +277,8 @@ for details. .. class:: ChangesBuilder This builder produces an HTML overview of all :rst:dir:`versionadded`, - :rst:dir:`versionchanged` and :rst:dir:`deprecated` directives for the current - :confval:`version`. This is useful to generate a ChangeLog file, for + :rst:dir:`versionchanged` and :rst:dir:`deprecated` directives for the + current :confval:`version`. This is useful to generate a ChangeLog file, for example. .. autoattribute:: name diff --git a/doc/changes.rst b/doc/changes.rst index d5927a72..e4263687 100644 --- a/doc/changes.rst +++ b/doc/changes.rst @@ -1,5 +1,7 @@ :tocdepth: 2 +.. default-role:: any + .. _changes: Changes in Sphinx diff --git a/doc/conf.py b/doc/conf.py index 9640e2ed..4a6f8f58 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -5,6 +5,7 @@ import re import sphinx + extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', 'sphinx.ext.autosummary', 'sphinx.ext.extlinks'] @@ -82,7 +83,7 @@ texinfo_documents = [ # We're not using intersphinx right now, but if we did, this would be part of # the mapping: -intersphinx_mapping = {'python': ('http://docs.python.org/dev', None)} +intersphinx_mapping = {'python': ('http://docs.python.org/2/', None)} # Sphinx document translation with sphinx gettext feature uses these settings: locale_dirs = ['locale/'] diff --git a/doc/config.rst b/doc/config.rst index 26079e69..e7e2455d 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -45,7 +45,8 @@ Important points to note: * There is a special object named ``tags`` available in the config file. It can be used to query and change the tags (see :ref:`tags`). Use ``tags.has('tag')`` to query, ``tags.add('tag')`` and ``tags.remove('tag')`` - to change. + to change. Only tags set via the ``-t`` command-line option or via + ``tags.add('tag')`` can be queried using ``tags.has('tag')``. Note that the current builder tag is not available in ``conf.py``, as it is created *after* the builder is initialized. @@ -115,44 +116,16 @@ General configuration .. versionadded:: 1.0 -.. confval:: unused_docs - - A list of document names that are present, but not currently included in the - toctree. Use this setting to suppress the warning that is normally emitted - in that case. - - .. deprecated:: 1.0 - Use :confval:`exclude_patterns` instead. - -.. confval:: exclude_trees - - A list of directory paths, relative to the source directory, that are to be - recursively excluded from the search for source files, that is, their - subdirectories won't be searched too. The default is ``[]``. - - .. versionadded:: 0.4 - - .. deprecated:: 1.0 - Use :confval:`exclude_patterns` instead. - -.. confval:: exclude_dirnames - - A list of directory names that are to be excluded from any recursive - operation Sphinx performs (e.g. searching for source files or copying static - files). This is useful, for example, to exclude version-control-specific - directories like ``'CVS'``. The default is ``[]``. - - .. versionadded:: 0.5 - - .. deprecated:: 1.0 - Use :confval:`exclude_patterns` instead. - .. confval:: templates_path A list of paths that contain extra templates (or templates that overwrite builtin/theme-specific templates). Relative paths are taken as relative to the configuration directory. + .. versionchanged:: 1.3 + As these files are not meant to be built, they are automatically added to + :confval:`exclude_patterns`. + .. confval:: template_bridge A string with the fully-qualified name of a callable (or simply a class) that @@ -228,6 +201,19 @@ General configuration .. versionadded:: 1.0 +.. confval:: needs_extensions + + This value can be a dictionary specifying version requirements for extensions + in :confval:`extensions`, e.g. ``needs_extensions = + {'sphinxcontrib.something': '1.5'}``. The version strings should be in the + form ``major.minor``. Requirements do not have to be specified for all + extensions, only for those you want to check. + + This requires that the extension specifies its version to Sphinx (see + :ref:`dev-extensions` for how to do that). + + .. versionadded:: 1.3 + .. confval:: nitpicky If true, Sphinx will warn about *all* references where the target cannot be @@ -245,6 +231,30 @@ General configuration .. versionadded:: 1.1 +.. confval:: numfig + + If true, figures, tables and code-blocks are automatically numbered if they + has caption. For now, it works only with the HTML builder. Default is ``False``. + + .. versionadded:: 1.3 + +.. confval:: numfig_prefix + + A dictionary mapping ``'figure'``, ``'table'`` and ``'code-block'`` to + strings that are used for prefix of figure numbers. Default is to use + ``'Fig. %s'`` for ``'figure'``, ``'Table %s'`` for ``'table'`` and + ``'Listing %s'`` for ``'code-block'``. + + .. versionadded:: 1.3 + +.. confval:: numfig_secnum_depth + + The scope of figure numbers, that is, the numfig feature numbers figures + in which scope. ``0`` means "whole document". ``1`` means "in a section". + Sphinx numbers like x.1, x.2, x.3... ``2`` means "in a subsection". Sphinx + numbers like x.x.1, x.x.2, x.x.3..., and so on. Default is ``1``. + + .. versionadded:: 1.3 Project information ------------------- @@ -341,8 +351,8 @@ Project information If true, doctest flags (comments looking like ``# doctest: FLAG, ...``) at the ends of lines and ``<BLANKLINE>`` markers are removed for all code blocks showing interactive Python sessions (i.e. doctests). Default is - true. See the extension :mod:`~sphinx.ext.doctest` for more possibilities - of including doctests. + ``True``. See the extension :mod:`~sphinx.ext.doctest` for more + possibilities of including doctests. .. versionadded:: 1.0 .. versionchanged:: 1.1 @@ -354,7 +364,7 @@ Project information Options for internationalization -------------------------------- -These options influence Sphinx' *Native Language Support*. See the +These options influence Sphinx's *Native Language Support*. See the documentation on :ref:`intl` for details. .. confval:: language @@ -435,6 +445,50 @@ documentation on :ref:`intl` for details. By default, the document ``markup/code.rst`` ends up in the ``markup`` text domain. With this option set to ``False``, it is ``markup/code``. +.. confval:: gettext_uuid + + If true, Sphinx generates uuid information for version tracking in message + catalogs. It is used for: + + * Add uid line for each msgids in .pot files. + * Calculate similarity between new msgids and previously saved old msgids. + This calculation takes a long time. + + If you want to accelerate the calculation, you can use + ``python-levenshtein`` 3rd-party package written in C by using + :command:`pip install python-levenshtein`. + + The default is ``False``. + + .. versionadded:: 1.3 + +.. confval:: gettext_location + + If true, Sphinx generates location information for messages in message + catalogs. + + The default is ``True``. + + .. versionadded:: 1.3 + +.. confval:: gettext_auto_build + + If true, Sphinx builds mo file for each translation catalog files. + + The default is ``True``. + + .. versionadded:: 1.3 + +.. confval:: gettext_enables + + To specify names to enable gettext extracting and translation applying for + i18n. You can specify below names: + + :index: index terms + + The default is ``[]``. + + .. versionadded:: 1.3 .. _html-options: @@ -442,7 +496,7 @@ Options for HTML output ----------------------- These options influence HTML as well as HTML Help output, and other builders -that use Sphinx' HTMLWriter class. +that use Sphinx's HTMLWriter class. .. confval:: html_theme @@ -470,14 +524,14 @@ that use Sphinx' HTMLWriter class. .. confval:: html_style The style sheet to use for HTML pages. A file of that name must exist either - in Sphinx' :file:`static/` path, or in one of the custom paths given in + in Sphinx's :file:`static/` path, or in one of the custom paths given in :confval:`html_static_path`. Default is the stylesheet given by the selected theme. If you only want to add or override a few things compared to the theme's stylesheet, use CSS ``@import`` to import the theme's stylesheet. .. confval:: html_title - The "title" for HTML documentation generated with Sphinx' own templates. + The "title" for HTML documentation generated with Sphinx's own templates. This is appended to the ``<title>`` tag of individual pages, and used in the navigation bar as the "topmost" element. It defaults to :samp:`'{<project>} v{<revision>} documentation'` (with the values coming from the config @@ -513,9 +567,10 @@ that use Sphinx' HTMLWriter class. .. confval:: html_favicon If given, this must be the name of an image file (path relative to the - :term:`configuration directory`) that is the favicon of the docs. Modern browsers use this - as icon for tabs, windows and bookmarks. It should be a Windows-style icon - file (``.ico``), which is 16x16 or 32x32 pixels large. Default: ``None``. + :term:`configuration directory`) that is the favicon of the docs. Modern + browsers use this as the icon for tabs, windows and bookmarks. It should + be a Windows-style icon file (``.ico``), which is 16x16 or 32x32 + pixels large. Default: ``None``. .. versionadded:: 0.4 The image file will be copied to the ``_static`` directory of the output @@ -557,8 +612,9 @@ that use Sphinx' HTMLWriter class. .. confval:: html_use_smartypants - If true, *SmartyPants* will be used to convert quotes and dashes to - typographically correct entities. Default: ``True``. + If true, `SmartyPants <http://daringfireball.net/projects/smartypants/>`_ + will be used to convert quotes and dashes to typographically correct + entities. Default: ``True``. .. confval:: html_add_permalinks @@ -600,7 +656,8 @@ that use Sphinx' HTMLWriter class. Builtin sidebar templates that can be rendered are: - * **localtoc.html** -- a fine-grained table of contents of the current document + * **localtoc.html** -- a fine-grained table of contents of the current + document * **globaltoc.html** -- a coarse-grained table of contents for the whole documentation set, collapsed * **relations.html** -- two links to the previous and next documents @@ -692,7 +749,7 @@ that use Sphinx' HTMLWriter class. .. confval:: html_use_opensearch - If nonempty, an `OpenSearch <http://opensearch.org>` description file will be + If nonempty, an `OpenSearch <http://opensearch.org>`_ description file will be output, and all pages will contain a ``<link>`` tag referring to it. Since OpenSearch doesn't support relative URLs for its search page location, the value of this option must be the base URL from which these documents are @@ -717,13 +774,16 @@ that use Sphinx' HTMLWriter class. .. confval:: html_translator_class A string with the fully-qualified name of a HTML Translator class, that is, a - subclass of Sphinx' :class:`~sphinx.writers.html.HTMLTranslator`, that is used - to translate document trees to HTML. Default is ``None`` (use the builtin - translator). + subclass of Sphinx's :class:`~sphinx.writers.html.HTMLTranslator`, that is + used to translate document trees to HTML. Default is ``None`` (use the + builtin translator). + + .. seealso:: :meth:`~sphinx.application.Sphinx.set_translator` .. confval:: html_show_copyright - If true, "(C) Copyright ..." is shown in the HTML footer. Default is ``True``. + If true, "(C) Copyright ..." is shown in the HTML footer. Default is + ``True``. .. versionadded:: 1.0 @@ -766,10 +826,37 @@ that use Sphinx' HTMLWriter class. Support is present for these languages: + * ``da`` -- Danish + * ``nl`` -- Dutch * ``en`` -- English + * ``fi`` -- Finnish + * ``fr`` -- French + * ``de`` -- German + * ``hu`` -- Hungarian + * ``it`` -- Italian * ``ja`` -- Japanese + * ``no`` -- Norwegian + * ``pr`` -- Portuguese + * ``ro`` -- Romanian + * ``ru`` -- Russian + * ``es`` -- Spanish + * ``sv`` -- Swedish + * ``tr`` -- Turkish + + .. admonition:: Accelerating build speed + + Each language (except Japanese) provides its own stemming algorithm. + Sphinx uses a Python implementation by default. You can use a C + implementation to accelerate building the index file. + + * `PorterStemmer <https://pypi.python.org/pypi/PorterStemmer>`_ (``en``) + * `PyStemmer <https://pypi.python.org/pypi/PyStemmer>`_ (all languages) .. versionadded:: 1.1 + With support for ``en`` and ``ja``. + + .. versionchanged:: 1.3 + Added additional languages. .. confval:: html_search_options @@ -791,7 +878,7 @@ that use Sphinx' HTMLWriter class. .. confval:: html_search_scorer - The name of a javascript file (relative to the configuration directory) that + The name of a JavaScript file (relative to the configuration directory) that implements a search results scorer. If empty, the default will be used. .. XXX describe interface for scorer here @@ -900,7 +987,7 @@ the `Dublin Core metadata <http://dublincore.org/>`_. the optional guide information. See the OPF documentation at `<http://idpf.org/epub>`_ for details. If possible, default entries for the *cover* and *toc* types are automatically inserted. However, - the types can be explicitely overwritten if the default entries are not + the types can be explicitly overwritten if the default entries are not appropriate. Example:: epub_guide = (('cover', 'cover.html', u'Cover Page'),) @@ -940,8 +1027,8 @@ the `Dublin Core metadata <http://dublincore.org/>`_. .. confval:: epub_tocdup This flag determines if a toc entry is inserted again at the beginning of - it's nested toc listing. This allows easier navitation to the top of - a chapter, but can be confusing because it mixes entries of differnet + its nested toc listing. This allows easier navigation to the top of + a chapter, but can be confusing because it mixes entries of different depth in one list. The default value is ``True``. .. confval:: epub_tocscope @@ -1024,11 +1111,11 @@ These options influence LaTeX output. ``'John \and Sarah'``. * *documentclass*: Normally, one of ``'manual'`` or ``'howto'`` (provided by Sphinx). Other document classes can be given, but they must include the - "sphinx" package in order to define Sphinx' custom LaTeX commands. - "howto" documents will not get appendices. Also, howtos will have a simpler - title page. + "sphinx" package in order to define Sphinx's custom LaTeX commands. "howto" + documents will not get appendices. Also, howtos will have a simpler title + page. - * *toctree_only*: Must be ``True`` or ``False``. If ``True``, the *startdoc* + * *toctree_only*: Must be ``True`` or ``False``. If true, the *startdoc* document itself is not included in the output, only the documents referenced by it via TOC trees. With this option, you can put extra stuff in the master document that shows up in the HTML, but not the LaTeX output. @@ -1135,6 +1222,12 @@ These options influence LaTeX output. "Rejne". You can also set this to ``''`` to disable fncychap. ``'preamble'`` Additional preamble content, default empty. + ``'figure_align'`` + Latex figure float alignment, default 'htbp' (here, top, bottom, page). + Whenever an image doesn't fit into the current page, it will be + 'floated' into the next page but may be preceded by any other text. + If you don't like this behavior, use 'H' which will disable floating + and position figures strictly in the order they appear in the source. ``'footer'`` Additional footer content (before the indices), default empty. @@ -1167,7 +1260,8 @@ These options influence LaTeX output. ``'\\printindex'``. Override if you want to generate the index differently or append some content after the index. - * Keys that are set by other options and therefore should not be overridden are: + * Keys that are set by other options and therefore should not be overridden + are: ``'docclass'`` ``'classoptions'`` @@ -1324,7 +1418,7 @@ These options influence Texinfo output. file. * *category*: Specifies the section which this entry will appear in the top-level ``DIR`` menu file. - * *toctree_only*: Must be ``True`` or ``False``. If ``True``, the *startdoc* + * *toctree_only*: Must be ``True`` or ``False``. If true, the *startdoc* document itself is not included in the output, only the documents referenced by it via TOC trees. With this option, you can put extra stuff in the master document that shows up in the HTML, but not the Texinfo @@ -1400,7 +1494,6 @@ These options influence Texinfo output. ``'project'`` ``'release'`` ``'title'`` - ``'direntry'`` .. versionadded:: 1.1 @@ -1434,9 +1527,9 @@ Options for the linkcheck builder .. confval:: linkcheck_anchors - True or false, whether to check the validity of ``#anchor``\ s in links. - Since this requires downloading the whole document, it's considerably slower - when enabled. Default is ``True``. + If true, check the validity of ``#anchor``\ s in links. Since this requires + downloading the whole document, it's considerably slower when enabled. + Default is ``True``. .. versionadded:: 1.2 @@ -1446,7 +1539,7 @@ Options for the XML builder .. confval:: xml_pretty - If True, pretty-print the XML. Default is ``True``. + If true, pretty-print the XML. Default is ``True``. .. versionadded:: 1.2 diff --git a/doc/contents.rst b/doc/contents.rst index d3fd3c8e..a51910b8 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -26,6 +26,7 @@ Sphinx documentation contents devguide changes examples + authors Indices and tables diff --git a/doc/develop.rst b/doc/develop.rst index aad3ff1e..5110aa3a 100644 --- a/doc/develop.rst +++ b/doc/develop.rst @@ -55,6 +55,7 @@ This is the current list of contributed extensions in that repository: - hyphenator: client-side hyphenation of HTML using hyphenator_ - inlinesyntaxhighlight_: inline syntax highlighting - lassodomain: a domain for documenting Lasso_ source code +- libreoffice: an extension to include any drawing supported by LibreOffice (e.g. odg, vsd...). - lilypond: an extension inserting music scripts from Lilypond_ in PNG format. - makedomain_: a domain for `GNU Make`_ - matlabdomain: document MATLAB_ code. @@ -68,7 +69,8 @@ This is the current list of contributed extensions in that repository: - paverutils: an alternate integration of Sphinx with Paver_. - phpdomain: an extension for PHP support - plantuml: embed UML diagram by using PlantUML_ -- py_directive: Execute python code in a ``py`` directive and return a math node. +- py_directive: Execute python code in a ``py`` directive and return a math + node. - rawfiles: copy raw files, like a CNAME. - requirements: declare requirements wherever you need (e.g. in test docstrings), mark statuses and collect them in a single list diff --git a/doc/devguide.rst b/doc/devguide.rst index fccdd3fa..9d85ec0b 100644 --- a/doc/devguide.rst +++ b/doc/devguide.rst @@ -54,6 +54,23 @@ the Mercurial repository on BitBucket and then submit a pull request after committing the changes. The pull request will then need to be approved by one of the core developers before it is merged into the main repository. +#. Check for open issues or open a fresh issue to start a discussion around a + feature idea or a bug. There are `Non Assigned`_ issues. +#. If you feel uncomfortable or uncertain about an issue or your changes, feel + free to email sphinx-dev@googlegroups.com. +#. Fork `the repository`_ on Bitbucket to start making your changes to the + **default** branch for next major version, or **stable** branch for next + minor version. +#. Write a test which shows that the bug was fixed or that the feature works + as expected. +#. Send a pull request and bug the maintainer until it gets merged and + published. Make sure to add yourself to AUTHORS_ and the change to + CHANGES_. + +.. _`the repository`: https://bitbucket.org/birkenfeld/sphinx +.. _AUTHORS: https://bitbucket.org/birkenfeld/sphinx/src/tip/AUTHORS +.. _CHANGES: https://bitbucket.org/birkenfeld/sphinx/src/tip/CHANGES +.. _Non Assigned: https://bitbucket.org/birkenfeld/sphinx/issues?status=new&status=open&responsible= Getting Started ~~~~~~~~~~~~~~~ @@ -113,8 +130,13 @@ These are the basic steps needed to start developing on Sphinx. * For bug fixes, first add a test that fails without your changes and passes after they are applied. -#. Please add a bullet point to :file:`CHANGES` if the fix or feature is not trivial - (small doc updates, typo fixes). Then commit:: + * Tests that need a sphinx-build run should be integrated in one of the + existing test modules if possible. New tests that to ``@with_app`` and + then ``build_all`` for a few assertions are not good since *the test suite + should not take more than a minute to run*. + +#. Please add a bullet point to :file:`CHANGES` if the fix or feature is not + trivial (small doc updates, typo fixes). Then commit:: hg commit -m '#42: Add useful new feature that does this.' @@ -191,9 +213,9 @@ identifier and put ``sphinx.po`` in there. Don't forget to update the possible values for :confval:`language` in ``doc/config.rst``. The Sphinx core messages can also be translated on `Transifex -<https://www.transifex.com/>`_. There exists a client tool named ``tx`` in the Python -package "transifex_client", which can be used to pull translations in ``.po`` -format from Transifex. To do this, go to ``sphinx/locale`` and then run +<https://www.transifex.com/>`_. There exists a client tool named ``tx`` in the +Python package "transifex_client", which can be used to pull translations in +``.po`` format from Transifex. To do this, go to ``sphinx/locale`` and then run ``tx pull -f -l LANG`` where LANG is an existing language identifier. It is good practice to run ``python setup.py update_catalog`` afterwards to make sure the ``.po`` file has the canonical Babel formatting. @@ -235,11 +257,23 @@ Debugging Tips * Use ``node.pformat()`` and ``node.asdom().toxml()`` to generate a printable representation of the document structure. -* Set the configuration variable :confval:`keep_warnings` to True so warnings - will be displayed in the generated output. +* Set the configuration variable :confval:`keep_warnings` to ``True`` so + warnings will be displayed in the generated output. -* Set the configuration variable :confval:`nitpicky` to True so that Sphinx +* Set the configuration variable :confval:`nitpicky` to ``True`` so that Sphinx will complain about references without a known target. * Set the debugging options in the `Docutils configuration file <http://docutils.sourceforge.net/docs/user/config.html>`_. + +* JavaScript stemming algorithms in `sphinx/search/*.py` (except `en.py`) are + generated by this + `modified snowballcode generator <https://github.com/shibukawa/snowball>`_. + Generated `JSX <http://jsx.github.io/>`_ files are + in `this repository <https://github.com/shibukawa/snowball-stemmer.jsx>`_. + You can get the resulting JavaScript files using the following command: + + .. code-block:: bash + + $ npm install + $ node_modules/.bin/grunt build # -> dest/*.global.js diff --git a/doc/domains.rst b/doc/domains.rst index 4b5a9032..4bfc91ec 100644 --- a/doc/domains.rst +++ b/doc/domains.rst @@ -127,7 +127,8 @@ declarations: This directive marks the beginning of the description of a module (or package submodule, in which case the name should be fully qualified, including the - package name). It does not create content (like e.g. :rst:dir:`py:class` does). + package name). It does not create content (like e.g. :rst:dir:`py:class` + does). This directive will also cause an entry in the global module index. @@ -157,17 +158,6 @@ declarations: The following directives are provided for module and class contents: -.. rst:directive:: .. py:data:: name - - Describes global data in a module, including both variables and values used - as "defined constants." Class and object attributes are not documented - using this environment. - -.. rst:directive:: .. py:exception:: name - - Describes an exception class. The signature can, but need not include - parentheses with constructor arguments. - .. rst:directive:: .. py:function:: name(parameters) Describes a module-level function. The signature should include the @@ -178,11 +168,23 @@ The following directives are provided for module and class contents: For methods you should use :rst:dir:`py:method`. - The description should include information about the parameters required and - how they are used (especially whether mutable objects passed as parameters - are modified), side effects, and possible exceptions. This information can - optionally be given in a structured form, see :ref:`info-field-lists`. A - small example may be provided. + The description normally includes information about the parameters required + and how they are used (especially whether mutable objects passed as + parameters are modified), side effects, and possible exceptions. + + This information can (in any ``py`` directive) optionally be given in a + structured form, see :ref:`info-field-lists`. + +.. rst:directive:: .. py:data:: name + + Describes global data in a module, including both variables and values used + as "defined constants." Class and object attributes are not documented + using this environment. + +.. rst:directive:: .. py:exception:: name + + Describes an exception class. The signature can, but need not include + parentheses with constructor arguments. .. rst:directive:: .. py:class:: name .. py:class:: name(parameters) @@ -374,7 +376,7 @@ a matching identifier is found: Reference a Python function; dotted names may be used. The role text needs not include trailing parentheses to enhance readability; they will be added automatically by Sphinx if the :confval:`add_function_parentheses` config - value is true (the default). + value is ``True`` (the default). .. rst:role:: py:data @@ -518,23 +520,26 @@ The C++ Domain The C++ domain (name **cpp**) supports documenting C++ projects. -The following directives are available: +The following directives are available. All declarations can start with a visibility statement +(``public``, ``private`` or ``protected``). + +.. rst:directive:: .. cpp:class:: class speicifer + + Describe a class/struct, possibly with specification of inheritance, e.g.,:: + + .. cpp:class:: SomeName::SomeClass : public MyBase, MyOtherBase -.. rst:directive:: .. cpp:class:: signatures - .. cpp:function:: signatures - .. cpp:member:: signatures - .. cpp:type:: signatures +.. rst:directive:: .. cpp:function:: (member-)function prototype - Describe a C++ object. Full signature specification is supported -- give the - signature as you would in the declaration. Here some examples:: + Describe a function or member function, e.g.,:: .. cpp:function:: bool namespaced::theclass::method(int arg1, std::string arg2) Describes a method with parameters and types. - .. cpp:function:: bool namespaced::theclass::method(arg1, arg2) + .. cpp:function:: bool namespaced::theclass::method(T1, T2) - Describes a method without types. + Describes a method with unnamed parameters. .. cpp:function:: const T &array<T>::operator[]() const @@ -548,43 +553,41 @@ The following directives are available: Describe a constexpr function here. - .. cpp:member:: std::string theclass::name - - .. cpp:member:: std::string theclass::name[N][M] - - .. cpp:type:: theclass::const_iterator - - Will be rendered like this: + .. cpp:function:: MyClass::MyClass(const MyClass&) = default - .. cpp:function:: bool namespaced::theclass::method(int arg1, std::string arg2) + Describe a copy constructor with default implementation. - Describes a method with parameters and types. +.. rst:directive:: .. cpp:member:: variable or member declaration - .. cpp:function:: bool namespaced::theclass::method(arg1, arg2) + Describe a varible or member variable, e.g.,:: - Describes a method without types. + .. cpp:member:: std::string theclass::name - .. cpp:function:: const T &array<T>::operator[]() const + .. cpp:member:: std::string theclass::name[N][M] - Describes the constant indexing operator of a templated array. +.. rst:directive:: .. cpp:type:: typedef-like declaration + .. cpp:type:: name - .. cpp:function:: operator bool() const + Describe a type as in a typedef declaration, or the name of a type with unspecified type, e.g.,:: - Describe a casting operator here. + .. cpp:type:: std::vector<int> MyList - .. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept + A typedef-like declaration of a type. - Describe a constexpr function here. + .. cpp:type:: theclass::const_iterator - .. cpp:member:: std::string theclass::name + Declaration of a type alias with unspecified type. - .. cpp:member:: std::string theclass::name[N][M] +.. rst:directive:: .. cpp:namespace:: namespace - .. cpp:type:: theclass::const_iterator + Select the current namespace for the following objects. Note that the namespace + does not need to correspond to C++ namespaces, but can end in names of classes, e.g.,:: -.. rst:directive:: .. cpp:namespace:: namespace + .. cpp:namespace:: Namespace1::Namespace2::SomeClass::AnInnerClass - Select the current C++ namespace for the following objects. + All following objects will be defined as if their name were declared with the namespace + prepended. The following cross-references will be search for by both their specified name + and with the namespace prepended. .. _cpp-roles: @@ -596,12 +599,12 @@ These roles link to the given object types: cpp:member cpp:type - Reference a C++ object. You can give the full signature (and need to, for + Reference a C++ object. You can give the full specification (and need to, for overloaded functions.) .. note:: - Sphinx' syntax to give references a custom title can interfere with + Sphinx's syntax to give references a custom title can interfere with linking to template classes, if nothing follows the closing angle bracket, i.e. if the link looks like this: ``:cpp:class:`MyClass<T>```. This is interpreted as a link to ``T`` with a title of ``MyClass``. @@ -617,6 +620,12 @@ These roles link to the given object types: specific overload. Currently Sphinx will link to the first overloaded version of the method / function. +.. admonition:: Note on Template Delcarations + + The C++ domain currently does not support template classes/functions/aliases/variables + (e.g., ``template<typename T> MyClass``), only template instantiations + (e.g., ``MyClass<T>``). + The Standard Domain ------------------- @@ -654,9 +663,9 @@ There is a set of directives allowing documenting command-line programs: .. rst:directive:: .. program:: name - Like :rst:dir:`py:currentmodule`, this directive produces no output. Instead, it - serves to notify Sphinx that all following :rst:dir:`option` directives - document options for the program called *name*. + Like :rst:dir:`py:currentmodule`, this directive produces no output. + Instead, it serves to notify Sphinx that all following :rst:dir:`option` + directives document options for the program called *name*. If you use :rst:dir:`program`, you have to qualify the references in your :rst:role:`option` roles by the program name, so if you have the following diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst index 7f646985..844c6368 100644 --- a/doc/ext/autodoc.rst +++ b/doc/ext/autodoc.rst @@ -35,6 +35,16 @@ hand-written documentation, this technique eases the pain of having to maintain two locations for documentation, while at the same time avoiding auto-generated-looking pure API documentation. +If you prefer `NumPy`_ or `Google`_ style docstrings over reStructuredText, +you can also enable the :mod:`napoleon <sphinx.ext.napoleon>` extension. +:mod:`napoleon <sphinx.ext.napoleon>` is a preprocessor that converts your +docstrings to correct reStructuredText before :mod:`autodoc` processes them. + +.. _Google: + http://google-styleguide.googlecode.com/svn/trunk/pyguide.html#Comments +.. _NumPy: + https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt + :mod:`autodoc` provides several directives that are versions of the usual :rst:dir:`py:module`, :rst:dir:`py:class` and so forth. On parsing time, they import the corresponding module and extract the docstring of the given objects, @@ -204,6 +214,12 @@ inserting them into the page source under a suitable :rst:dir:`py:module`, .. versionadded:: 1.2 + * Add a list of modules in the :confval:`autodoc_mock_imports` to prevent + import errors to halt the building process when some external dependencies + are not importable at build time. + + .. versionadded:: 1.3 + .. rst:directive:: autofunction autodata @@ -258,13 +274,14 @@ inserting them into the page source under a suitable :rst:dir:`py:module`, """Docstring for instance attribute spam.""" .. versionchanged:: 0.6 - :rst:dir:`autodata` and :rst:dir:`autoattribute` can now extract docstrings. + :rst:dir:`autodata` and :rst:dir:`autoattribute` can now extract + docstrings. .. versionchanged:: 1.1 Comment docs are now allowed on the same line after an assignment. .. versionchanged:: 1.2 - :rst:dir:`autodata` and :rst:dir:`autoattribute` have - an ``annotation`` option + :rst:dir:`autodata` and :rst:dir:`autoattribute` have an ``annotation`` + option. .. note:: @@ -344,6 +361,14 @@ There are also new config values that you can set: .. versionadded:: 1.1 +.. confval:: autodoc_mock_imports + + This value contains a list of modules to be mocked up. This is useful when + some external dependencies are not met at build time and break the building + process. + + .. versionadded:: 1.3 + Docstring preprocessing ----------------------- @@ -389,8 +414,8 @@ autodoc provides the following additional events: ``noindex`` that are true if the flag option of same name was given to the auto directive :param signature: function signature, as a string of the form - ``"(parameter_1, parameter_2)"``, or ``None`` if introspection didn't succeed - and signature wasn't specified in the directive. + ``"(parameter_1, parameter_2)"``, or ``None`` if introspection didn't + succeed and signature wasn't specified in the directive. :param return_annotation: function return annotation as a string of the form ``" -> annotation"``, or ``None`` if there is no return annotation @@ -421,8 +446,8 @@ member should be included in the documentation by using the following event: ``"attribute"``) :param name: the fully qualified name of the object :param obj: the object itself - :param skip: a boolean indicating if autodoc will skip this member if the user - handler does not override the decision + :param skip: a boolean indicating if autodoc will skip this member if the + user handler does not override the decision :param options: the options given to the directive: an object with attributes ``inherited_members``, ``undoc_members``, ``show_inheritance`` and ``noindex`` that are true if the flag option of same name was given to the diff --git a/doc/ext/autosummary.rst b/doc/ext/autosummary.rst index e3de1835..8548fbd5 100644 --- a/doc/ext/autosummary.rst +++ b/doc/ext/autosummary.rst @@ -15,15 +15,15 @@ one of them on a separate page makes them easier to read. The :mod:`sphinx.ext.autosummary` extension does this in two parts: -1. There is an :rst:dir:`autosummary` directive for generating summary listings that - contain links to the documented items, and short summary blurbs extracted - from their docstrings. +1. There is an :rst:dir:`autosummary` directive for generating summary listings + that contain links to the documented items, and short summary blurbs + extracted from their docstrings. 2. Optionally, the convenience script :program:`sphinx-autogen` or the new :confval:`autosummary_generate` config value can be used to generate short "stub" files for the entries listed in the :rst:dir:`autosummary` directives. - These files by default contain only the corresponding :mod:`sphinx.ext.autodoc` - directive, but can be customized with templates. + These files by default contain only the corresponding + :mod:`sphinx.ext.autodoc` directive, but can be customized with templates. .. rst:directive:: autosummary @@ -62,8 +62,8 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts: **Options** - * If you want the :rst:dir:`autosummary` table to also serve as a :rst:dir:`toctree` - entry, use the ``toctree`` option, for example:: + * If you want the :rst:dir:`autosummary` table to also serve as a + :rst:dir:`toctree` entry, use the ``toctree`` option, for example:: .. autosummary:: :toctree: DIRNAME @@ -78,8 +78,8 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts: directory. If no argument is given, output is placed in the same directory as the file that contains the directive. - * If you don't want the :rst:dir:`autosummary` to show function signatures in the - listing, include the ``nosignatures`` option:: + * If you don't want the :rst:dir:`autosummary` to show function signatures in + the listing, include the ``nosignatures`` option:: .. autosummary:: :nosignatures: @@ -112,8 +112,8 @@ For example, the command :: $ sphinx-autogen -o generated *.rst -will read all :rst:dir:`autosummary` tables in the :file:`*.rst` files that have the -``:toctree:`` option set, and output corresponding stub pages in directory +will read all :rst:dir:`autosummary` tables in the :file:`*.rst` files that have +the ``:toctree:`` option set, and output corresponding stub pages in directory ``generated`` for all documented items. The generated pages by default contain text of the form:: diff --git a/doc/ext/doctest.rst b/doc/ext/doctest.rst index 554987ee..9b1b4e6d 100644 --- a/doc/ext/doctest.rst +++ b/doc/ext/doctest.rst @@ -142,8 +142,8 @@ names. The following is an example for the usage of the directives. The test via -:rst:dir:`doctest` and the test via :rst:dir:`testcode` and :rst:dir:`testoutput` are -equivalent. :: +:rst:dir:`doctest` and the test via :rst:dir:`testcode` and +:rst:dir:`testoutput` are equivalent. :: The parrot module ================= @@ -236,5 +236,5 @@ There are also these config values for customizing the doctest extension: Note though that you can't have blank lines in reST doctest blocks. They will be interpreted as one block ending and another one starting. Also, removal of ``<BLANKLINE>`` and ``# doctest:`` options only works in - :rst:dir:`doctest` blocks, though you may set :confval:`trim_doctest_flags` to - achieve that in all code blocks with Python console content. + :rst:dir:`doctest` blocks, though you may set :confval:`trim_doctest_flags` + to achieve that in all code blocks with Python console content. diff --git a/doc/ext/example_google.py b/doc/ext/example_google.py new file mode 100644 index 00000000..c94dcdf1 --- /dev/null +++ b/doc/ext/example_google.py @@ -0,0 +1,223 @@ +# -*- coding: utf-8 -*- +"""Example Google style docstrings. + +This module demonstrates documentation as specified by the `Google Python +Style Guide`_. Docstrings may extend over multiple lines. Sections are created +with a section header and a colon followed by a block of indented text. + +Example: + Examples can be given using either the ``Example`` or ``Examples`` + sections. Sections support any reStructuredText formatting, including + literal blocks:: + + $ python example_google.py + +Section breaks are created by simply resuming unindented text. Section breaks +are also implicitly created anytime a new section starts. + +Attributes: + module_level_variable (int): Module level variables may be documented in + either the ``Attributes`` section of the module docstring, or in an + inline docstring immediately following the variable. + + Either form is acceptable, but the two should not be mixed. Choose + one convention to document module level variables and be consistent + with it. + +.. _Google Python Style Guide: + http://google-styleguide.googlecode.com/svn/trunk/pyguide.html + +""" + +module_level_variable = 12345 + + +def module_level_function(param1, param2=None, *args, **kwargs): + """This is an example of a module level function. + + Function parameters should be documented in the ``Args`` section. The name + of each parameter is required. The type and description of each parameter + is optional, but should be included if not obvious. + + If the parameter itself is optional, it should be noted by adding + ", optional" to the type. If \*args or \*\*kwargs are accepted, they + should be listed as \*args and \*\*kwargs. + + The format for a parameter is:: + + name (type): description + The description may span multiple lines. Following + lines should be indented. + + Multiple paragraphs are supported in parameter + descriptions. + + Args: + param1 (int): The first parameter. + param2 (str, optional): The second parameter. Defaults to None. + Second line of description should be indented. + *args: Variable length argument list. + **kwargs: Arbitrary keyword arguments. + + Returns: + bool: True if successful, False otherwise. + + The return type is optional and may be specified at the beginning of + the ``Returns`` section followed by a colon. + + The ``Returns`` section may span multiple lines and paragraphs. + Following lines should be indented to match the first line. + + The ``Returns`` section supports any reStructuredText formatting, + including literal blocks:: + + { + 'param1': param1, + 'param2': param2 + } + + Raises: + AttributeError: The ``Raises`` section is a list of all exceptions + that are relevant to the interface. + ValueError: If `param2` is equal to `param1`. + + """ + if param1 == param2: + raise ValueError('param1 may not be equal to param2') + return True + + +def example_generator(n): + """Generators have a ``Yields`` section instead of a ``Returns`` section. + + Args: + n (int): The upper limit of the range to generate, from 0 to `n` - 1 + + Yields: + int: The next number in the range of 0 to `n` - 1 + + Examples: + Examples should be written in doctest format, and should illustrate how + to use the function. + + >>> print [i for i in example_generator(4)] + [0, 1, 2, 3] + + """ + for i in range(n): + yield i + + +class ExampleError(Exception): + """Exceptions are documented in the same way as classes. + + The __init__ method may be documented in either the class level + docstring, or as a docstring on the __init__ method itself. + + Either form is acceptable, but the two should not be mixed. Choose one + convention to document the __init__ method and be consistent with it. + + Note: + Do not include the `self` parameter in the ``Args`` section. + + Args: + msg (str): Human readable string describing the exception. + code (int, optional): Error code, defaults to 2. + + Attributes: + msg (str): Human readable string describing the exception. + code (int): Exception error code. + + """ + def __init__(self, msg, code=2): + self.msg = msg + self.code = code + + +class ExampleClass(object): + """The summary line for a class docstring should fit on one line. + + If the class has public attributes, they should be documented here + in an ``Attributes`` section and follow the same formatting as a + function's ``Args`` section. + + Attributes: + attr1 (str): Description of `attr1`. + attr2 (list of str): Description of `attr2`. + attr3 (int): Description of `attr3`. + + """ + def __init__(self, param1, param2, param3=0): + """Example of docstring on the __init__ method. + + The __init__ method may be documented in either the class level + docstring, or as a docstring on the __init__ method itself. + + Either form is acceptable, but the two should not be mixed. Choose one + convention to document the __init__ method and be consistent with it. + + Note: + Do not include the `self` parameter in the ``Args`` section. + + Args: + param1 (str): Description of `param1`. + param2 (list of str): Description of `param2`. Multiple + lines are supported. + param3 (int, optional): Description of `param3`, defaults to 0. + + """ + self.attr1 = param1 + self.attr2 = param2 + self.attr3 = param3 + + def example_method(self, param1, param2): + """Class methods are similar to regular functions. + + Note: + Do not include the `self` parameter in the ``Args`` section. + + Args: + param1: The first parameter. + param2: The second parameter. + + Returns: + True if successful, False otherwise. + + """ + return True + + def __special__(self): + """By default special members with docstrings are included. + + Special members are any methods or attributes that start with and + end with a double underscore. Any special member with a docstring + will be included in the output. + + This behavior can be disabled by changing the following setting in + Sphinx's conf.py:: + + napoleon_include_special_with_doc = False + + """ + pass + + def __special_without_docstring__(self): + pass + + def _private(self): + """By default private members are not included. + + Private members are any methods or attributes that start with an + underscore and are *not* special. By default they are not included + in the output. + + This behavior can be changed such that private members *are* included + by changing the following setting in Sphinx's conf.py:: + + napoleon_include_private_with_doc = True + + """ + pass + + def _private_without_docstring(self): + pass diff --git a/doc/ext/example_google.rst b/doc/ext/example_google.rst new file mode 100644 index 00000000..06508082 --- /dev/null +++ b/doc/ext/example_google.rst @@ -0,0 +1,15 @@ +:orphan: + +.. _example_google: + +Example Google Style Python Docstrings +====================================== + +.. seealso:: + + :ref:`example_numpy` + +Download: :download:`example_google.py <example_google.py>` + +.. literalinclude:: example_google.py + :language: python diff --git a/doc/ext/example_numpy.py b/doc/ext/example_numpy.py new file mode 100644 index 00000000..df1d20e6 --- /dev/null +++ b/doc/ext/example_numpy.py @@ -0,0 +1,272 @@ +# -*- coding: utf-8 -*- +"""Example NumPy style docstrings. + +This module demonstrates documentation as specified by the `NumPy +Documentation HOWTO`_. Docstrings may extend over multiple lines. Sections +are created with a section header followed by an underline of equal length. + +Example +------- +Examples can be given using either the ``Example`` or ``Examples`` +sections. Sections support any reStructuredText formatting, including +literal blocks:: + + $ python example_numpy.py + + +Section breaks are created with two blank lines. Section breaks are also +implicitly created anytime a new section starts. Section bodies *may* be +indented: + +Notes +----- + This is an example of an indented section. It's like any other section, + but the body is indented to help it stand out from surrounding text. + +If a section is indented, then a section break is created simply by +resuming unindented text. + +Attributes +---------- +module_level_variable : int + Module level variables may be documented in either the ``Attributes`` + section of the module docstring, or in an inline docstring immediately + following the variable. + + Either form is acceptable, but the two should not be mixed. Choose + one convention to document module level variables and be consistent + with it. + +.. _NumPy Documentation HOWTO: + https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt + +""" + +module_level_variable = 12345 + + +def module_level_function(param1, param2=None, *args, **kwargs): + """This is an example of a module level function. + + Function parameters should be documented in the ``Parameters`` section. + The name of each parameter is required. The type and description of each + parameter is optional, but should be included if not obvious. + + If the parameter itself is optional, it should be noted by adding + ", optional" to the type. If \*args or \*\*kwargs are accepted, they + should be listed as \*args and \*\*kwargs. + + The format for a parameter is:: + + name : type + description + + The description may span multiple lines. Following lines + should be indented to match the first line of the description. + + Multiple paragraphs are supported in parameter + descriptions. + + Parameters + ---------- + param1 : int + The first parameter. + param2 : str, optional + The second parameter, defaults to None. + *args + Variable length argument list. + **kwargs + Arbitrary keyword arguments. + + Returns + ------- + bool + True if successful, False otherwise. + + The return type is not optional. The ``Returns`` section may span + multiple lines and paragraphs. Following lines should be indented to + match the first line of the description. + + The ``Returns`` section supports any reStructuredText formatting, + including literal blocks:: + + { + 'param1': param1, + 'param2': param2 + } + + Raises + ------ + AttributeError + The ``Raises`` section is a list of all exceptions + that are relevant to the interface. + ValueError + If `param2` is equal to `param1`. + + """ + if param1 == param2: + raise ValueError('param1 may not be equal to param2') + return True + + +def example_generator(n): + """Generators have a ``Yields`` section instead of a ``Returns`` section. + + Parameters + ---------- + n : int + The upper limit of the range to generate, from 0 to `n` - 1 + + Yields + ------ + int + The next number in the range of 0 to `n` - 1 + + Examples + -------- + Examples should be written in doctest format, and should illustrate how + to use the function. + + >>> print [i for i in example_generator(4)] + [0, 1, 2, 3] + + """ + for i in range(n): + yield i + + +class ExampleError(Exception): + """Exceptions are documented in the same way as classes. + + The __init__ method may be documented in either the class level + docstring, or as a docstring on the __init__ method itself. + + Either form is acceptable, but the two should not be mixed. Choose one + convention to document the __init__ method and be consistent with it. + + Note + ---- + Do not include the `self` parameter in the ``Parameters`` section. + + Parameters + ---------- + msg : str + Human readable string describing the exception. + code : int, optional + Error code, defaults to 2. + + Attributes + ---------- + msg : str + Human readable string describing the exception. + code : int + Exception error code. + + """ + def __init__(self, msg, code=2): + self.msg = msg + self.code = code + + +class ExampleClass(object): + """The summary line for a class docstring should fit on one line. + + If the class has public attributes, they should be documented here + in an ``Attributes`` section and follow the same formatting as a + function's ``Parameters`` section. + + Attributes + ---------- + attr1 : str + Description of `attr1`. + attr2 : list of str + Description of `attr2`. + attr3 : int + Description of `attr3`. + + """ + def __init__(self, param1, param2, param3=0): + """Example of docstring on the __init__ method. + + The __init__ method may be documented in either the class level + docstring, or as a docstring on the __init__ method itself. + + Either form is acceptable, but the two should not be mixed. Choose one + convention to document the __init__ method and be consistent with it. + + Note + ---- + Do not include the `self` parameter in the ``Parameters`` section. + + Parameters + ---------- + param1 : str + Description of `param1`. + param2 : list of str + Description of `param2`. Multiple + lines are supported. + param3 : int, optional + Description of `param3`, defaults to 0. + + """ + self.attr1 = param1 + self.attr2 = param2 + self.attr3 = param3 + + def example_method(self, param1, param2): + """Class methods are similar to regular functions. + + Note + ---- + Do not include the `self` parameter in the ``Parameters`` section. + + Parameters + ---------- + param1 + The first parameter. + param2 + The second parameter. + + Returns + ------- + bool + True if successful, False otherwise. + + """ + return True + + def __special__(self): + """By default special members with docstrings are included. + + Special members are any methods or attributes that start with and + end with a double underscore. Any special member with a docstring + will be included in the output. + + This behavior can be disabled by changing the following setting in + Sphinx's conf.py:: + + napoleon_include_special_with_doc = False + + """ + pass + + def __special_without_docstring__(self): + pass + + def _private(self): + """By default private members are not included. + + Private members are any methods or attributes that start with an + underscore and are *not* special. By default they are not included + in the output. + + This behavior can be changed such that private members *are* included + by changing the following setting in Sphinx's conf.py:: + + napoleon_include_private_with_doc = True + + """ + pass + + def _private_without_docstring(self): + pass diff --git a/doc/ext/example_numpy.rst b/doc/ext/example_numpy.rst new file mode 100644 index 00000000..a3b41613 --- /dev/null +++ b/doc/ext/example_numpy.rst @@ -0,0 +1,15 @@ +:orphan: + +.. _example_numpy: + +Example NumPy Style Python Docstrings +====================================== + +.. seealso:: + + :ref:`example_google` + +Download: :download:`example_numpy.py <example_numpy.py>` + +.. literalinclude:: example_numpy.py + :language: python diff --git a/doc/ext/intersphinx.rst b/doc/ext/intersphinx.rst index 7997472a..94047f8e 100644 --- a/doc/ext/intersphinx.rst +++ b/doc/ext/intersphinx.rst @@ -88,7 +88,7 @@ linking: This will download the corresponding :file:`objects.inv` file from the Internet and generate links to the pages under the given URI. The downloaded - inventory is cached in the Sphinx environment, so it must be redownloaded + inventory is cached in the Sphinx environment, so it must be re-downloaded whenever you do a full rebuild. A second example, showing the meaning of a non-``None`` value of the second @@ -99,8 +99,22 @@ linking: This will read the inventory from :file:`python-inv.txt` in the source directory, but still generate links to the pages under - ``http://docs.python.org/3.2``. It is up to you to update the inventory file as - new objects are added to the Python documentation. + ``http://docs.python.org/3.2``. It is up to you to update the inventory file + as new objects are added to the Python documentation. + + **Multiple target for the inventory** + + .. versionadded:: 1.3 + + Alternative files can be specified for each inventory. One can give a + tuple for the second inventory tuple item as shown in the following + example. This will read the inventory iterating through the (second) + tuple items until the first successful fetch. The primary use case for + this to specify mirror sites for server downtime of the primary + inventory:: + + intersphinx_mapping = {'python': ('http://docs.python.org/3.2', + (None, 'python-inv.txt'))} .. confval:: intersphinx_cache_limit diff --git a/doc/ext/linkcode.rst b/doc/ext/linkcode.rst index a69a5b1c..05d2cc6d 100644 --- a/doc/ext/linkcode.rst +++ b/doc/ext/linkcode.rst @@ -31,7 +31,8 @@ function that returns an URL based on the object. - ``py``: ``module`` (name of the module), ``fullname`` (name of the object) - ``c``: ``names`` (list of names for the object) - ``cpp``: ``names`` (list of names for the object) - - ``javascript``: ``object`` (name of the object), ``fullname`` (name of the item) + - ``javascript``: ``object`` (name of the object), ``fullname`` + (name of the item) Example: diff --git a/doc/ext/math.rst b/doc/ext/math.rst index 8b2924c7..4c154610 100644 --- a/doc/ext/math.rst +++ b/doc/ext/math.rst @@ -169,8 +169,8 @@ built: .. confval:: pngmath_add_tooltips - Default: true. If false, do not add the LaTeX code as an "alt" attribute for - math images. + Default: ``True``. If false, do not add the LaTeX code as an "alt" attribute + for math images. .. versionadded:: 1.1 @@ -197,7 +197,7 @@ Sphinx. The default is the ``http://`` URL that loads the JS files from the `MathJax CDN <http://docs.mathjax.org/en/latest/start.html>`_. If you want MathJax to - be available offline, you have to donwload it and set this value to a + be available offline, you have to download it and set this value to a different path. The path can be absolute or relative; if it is relative, it is relative to diff --git a/doc/ext/napoleon.rst b/doc/ext/napoleon.rst new file mode 100644 index 00000000..8d4a9311 --- /dev/null +++ b/doc/ext/napoleon.rst @@ -0,0 +1,380 @@ +:mod:`sphinx.ext.napoleon` -- Support for NumPy and Google style docstrings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. module:: sphinx.ext.napoleon + :synopsis: Support for NumPy and Google style docstrings + +.. moduleauthor:: Rob Ruana + +.. versionadded:: 1.3 + +Napoleon - *Marching toward legible docstrings* +=============================================== + +Are you tired of writing docstrings that look like this:: + + :param path: The path of the file to wrap + :type path: str + :param field_storage: The :class:`FileStorage` instance to wrap + :type field_storage: FileStorage + :param temporary: Whether or not to delete the file when the File + instance is destructed + :type temporary: bool + :returns: A buffered writable file descriptor + :rtype: BufferedFileStorage + +`ReStructuredText`_ is great, but it creates visually dense, hard to read +`docstrings`_. Compare the jumble above to the same thing rewritten +according to the `Google Python Style Guide`_:: + + Args: + path (str): The path of the file to wrap + field_storage (FileStorage): The :class:`FileStorage` instance to wrap + temporary (bool): Whether or not to delete the file when the File + instance is destructed + + Returns: + BufferedFileStorage: A buffered writable file descriptor + +Much more legible, no? + +Napoleon is a :doc:`../extensions` that enables Sphinx to parse both `NumPy`_ +and `Google`_ style docstrings - the style recommended by `Khan Academy`_. + +Napoleon is a pre-processor that parses `NumPy`_ and `Google`_ style +docstrings and converts them to reStructuredText before Sphinx attempts to +parse them. This happens in an intermediate step while Sphinx is processing +the documentation, so it doesn't modify any of the docstrings in your actual +source code files. + +.. _ReStructuredText: http://docutils.sourceforge.net/rst.html +.. _docstrings: http://www.python.org/dev/peps/pep-0287/ +.. _Google Python Style Guide: + http://google-styleguide.googlecode.com/svn/trunk/pyguide.html +.. _Google: + http://google-styleguide.googlecode.com/svn/trunk/pyguide.html#Comments +.. _NumPy: + https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt +.. _Khan Academy: + https://sites.google.com/a/khanacademy.org/forge/for-developers/styleguide/python#TOC-Docstrings + +Getting Started +--------------- + +1. After :doc:`setting up Sphinx <../tutorial>` to build your docs, enable + napoleon in the Sphinx `conf.py` file:: + + # conf.py + + # Add autodoc and napoleon to the extensions list + extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon'] + +2. Use `sphinx-apidoc` to build your API documentation:: + + $ sphinx-apidoc -f -o docs/source projectdir + + +Docstrings +---------- + +Napoleon interprets every docstring that :mod:`autodoc <sphinx.ext.autodoc>` +can find, including docstrings on: ``modules``, ``classes``, ``attributes``, +``methods``, ``functions``, and ``variables``. Inside each docstring, +specially formatted `Sections`_ are parsed and converted to +reStructuredText. + +All standard reStructuredText formatting still works as expected. + + +.. _Sections: + +Docstring Sections +------------------ + +All of the following section headers are supported: + + * ``Args`` *(alias of Parameters)* + * ``Arguments`` *(alias of Parameters)* + * ``Attributes`` + * ``Example`` + * ``Examples`` + * ``Keyword Args`` *(alias of Keyword Arguments)* + * ``Keyword Arguments`` + * ``Methods`` + * ``Note`` + * ``Notes`` + * ``Other Parameters`` + * ``Parameters`` + * ``Return`` *(alias of Returns)* + * ``Returns`` + * ``Raises`` + * ``References`` + * ``See Also`` + * ``Warning`` + * ``Warnings`` *(alias of Warning)* + * ``Warns`` + * ``Yields`` + +Google vs NumPy +--------------- + +Napoleon supports two styles of docstrings: `Google`_ and `NumPy`_. The +main difference between the two styles is that Google uses indention to +separate sections, whereas NumPy uses underlines. + +Google style:: + + def func(arg1, arg2): + """Summary line. + + Extended description of function. + + Args: + arg1 (int): Description of arg1 + arg2 (str): Description of arg2 + + Returns: + bool: Description of return value + + """ + return True + +NumPy style:: + + def func(arg1, arg2): + """Summary line. + + Extended description of function. + + Parameters + ---------- + arg1 : int + Description of arg1 + arg2 : str + Description of arg2 + + Returns + ------- + bool + Description of return value + + """ + return True + +NumPy style tends to require more vertical space, whereas Google style +tends to use more horizontal space. Google style tends to be easier to +read for short and simple docstrings, whereas NumPy style tends be easier +to read for long and in-depth docstrings. + +The `Khan Academy`_ recommends using Google style. + +The choice between styles is largely aesthetic, but the two styles should +not be mixed. Choose one style for your project and be consistent with it. + +.. seealso:: + + For complete examples: + + * :ref:`example_google` + * :ref:`example_numpy` + + +Configuration +============= + +Listed below are all the settings used by napoleon and their default +values. These settings can be changed in the Sphinx `conf.py` file. Make +sure that both "sphinx.ext.autodoc" and "sphinx.ext.napoleon" are +enabled in `conf.py`:: + + # conf.py + + # Add any Sphinx extension module names here, as strings + extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon'] + + # Napoleon settings + napoleon_google_docstring = True + napoleon_numpy_docstring = True + napoleon_include_private_with_doc = False + napoleon_include_special_with_doc = True + napoleon_use_admonition_for_examples = False + napoleon_use_admonition_for_notes = False + napoleon_use_admonition_for_references = False + napoleon_use_ivar = False + napoleon_use_param = True + napoleon_use_rtype = True + +.. _Google style: + http://google-styleguide.googlecode.com/svn/trunk/pyguide.html +.. _NumPy style: + https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt + + + +.. confval:: napoleon_google_docstring + + True to parse `Google style`_ docstrings. False to disable support + for Google style docstrings. *Defaults to True.* + +.. confval:: napoleon_numpy_docstring + + True to parse `NumPy style`_ docstrings. False to disable support + for NumPy style docstrings. *Defaults to True.* + +.. confval:: napoleon_include_private_with_doc + + True to include private members (like ``_membername``) with docstrings + in the documentation. False to fall back to Sphinx's default behavior. + *Defaults to False.* + + **If True**:: + + def _included(self): + """ + This will be included in the docs because it has a docstring + """ + pass + + def _skipped(self): + # This will NOT be included in the docs + pass + +.. confval:: napoleon_include_special_with_doc + + True to include special members (like ``__membername__``) with + docstrings in the documentation. False to fall back to Sphinx's + default behavior. *Defaults to True.* + + **If True**:: + + def __str__(self): + """ + This will be included in the docs because it has a docstring + """ + return unicode(self).encode('utf-8') + + def __unicode__(self): + # This will NOT be included in the docs + return unicode(self.__class__.__name__) + +.. confval:: napoleon_use_admonition_for_examples + + True to use the ``.. admonition::`` directive for the **Example** and + **Examples** sections. False to use the ``.. rubric::`` directive + instead. One may look better than the other depending on what HTML + theme is used. *Defaults to False.* + + This `NumPy style`_ snippet will be converted as follows:: + + Example + ------- + This is just a quick example + + **If True**:: + + .. admonition:: Example + + This is just a quick example + + **If False**:: + + .. rubric:: Example + + This is just a quick example + +.. confval:: napoleon_use_admonition_for_notes + + True to use the ``.. admonition::`` directive for **Notes** sections. + False to use the ``.. rubric::`` directive instead. *Defaults to False.* + + .. note:: The singular **Note** section will always be converted to a + ``.. note::`` directive. + + .. seealso:: + + :attr:`napoleon_use_admonition_for_examples` + +.. confval:: napoleon_use_admonition_for_references + + True to use the ``.. admonition::`` directive for **References** + sections. False to use the ``.. rubric::`` directive instead. + *Defaults to False.* + + .. seealso:: + + :attr:`napoleon_use_admonition_for_examples` + +.. confval:: napoleon_use_ivar + + True to use the ``:ivar:`` role for instance variables. False to use + the ``.. attribute::`` directive instead. *Defaults to False.* + + This `NumPy style`_ snippet will be converted as follows:: + + Attributes + ---------- + attr1 : int + Description of `attr1` + + **If True**:: + + :ivar attr1: Description of `attr1` + :vartype attr1: int + + **If False**:: + + .. attribute:: attr1 + + *int* + + Description of `attr1` + +.. confval:: napoleon_use_param + + True to use a ``:param:`` role for each function parameter. False to + use a single ``:parameters:`` role for all the parameters. + *Defaults to True.* + + This `NumPy style`_ snippet will be converted as follows:: + + Parameters + ---------- + arg1 : str + Description of `arg1` + arg2 : int, optional + Description of `arg2`, defaults to 0 + + **If True**:: + + :param arg1: Description of `arg1` + :type arg1: str + :param arg2: Description of `arg2`, defaults to 0 + :type arg2: int, optional + + **If False**:: + + :parameters: * **arg1** (*str*) -- + Description of `arg1` + * **arg2** (*int, optional*) -- + Description of `arg2`, defaults to 0 + +.. confval:: napoleon_use_rtype + + True to use the ``:rtype:`` role for the return type. False to output + the return type inline with the description. *Defaults to True.* + + This `NumPy style`_ snippet will be converted as follows:: + + Returns + ------- + bool + True if successful, False otherwise + + **If True**:: + + :returns: True if successful, False otherwise + :rtype: bool + + **If False**:: + + :returns: *bool* -- True if successful, False otherwise diff --git a/doc/ext/oldcmarkup.rst b/doc/ext/oldcmarkup.rst deleted file mode 100644 index 0fdd9fec..00000000 --- a/doc/ext/oldcmarkup.rst +++ /dev/null @@ -1,35 +0,0 @@ -:mod:`sphinx.ext.oldcmarkup` -- Compatibility extension for old C markup -======================================================================== - -.. module:: sphinx.ext.oldcmarkup - :synopsis: Allow further use of the pre-domain C markup -.. moduleauthor:: Georg Brandl - -.. versionadded:: 1.0 - - -This extension is a transition helper for projects that used the old -(pre-domain) C markup, i.e. the directives like ``cfunction`` and roles like -``cfunc``. Since the introduction of domains, they must be called by their -fully-qualified name (``c:function`` and ``c:func``, respectively) or, with the -default domain set to ``c``, by their new name (``function`` and ``func``). -(See :ref:`c-domain` for the details.) - -If you activate this extension, it will register the old names, and you can -use them like before Sphinx 1.0. The directives are: - -- ``cfunction`` -- ``cmember`` -- ``cmacro`` -- ``ctype`` -- ``cvar`` - -The roles are: - -- ``cdata`` -- ``cfunc`` -- ``cmacro`` -- ``ctype`` - -However, it is advised to migrate to the new markup -- this extension is a -compatibility convenience and will disappear in a future version of Sphinx. diff --git a/doc/ext/todo.rst b/doc/ext/todo.rst index 349d286a..c0d94ba1 100644 --- a/doc/ext/todo.rst +++ b/doc/ext/todo.rst @@ -13,18 +13,19 @@ There are two additional directives when using this extension: Use this directive like, for example, :rst:dir:`note`. - It will only show up in the output if :confval:`todo_include_todos` is true. + It will only show up in the output if :confval:`todo_include_todos` is + ``True``. .. rst:directive:: todolist This directive is replaced by a list of all todo directives in the whole - documentation, if :confval:`todo_include_todos` is true. + documentation, if :confval:`todo_include_todos` is ``True``. There is also an additional config value: .. confval:: todo_include_todos - If this is ``True``, :rst:dir:`todo` and :rst:dir:`todolist` produce output, else - they produce nothing. The default is ``False``. + If this is ``True``, :rst:dir:`todo` and :rst:dir:`todolist` produce output, + else they produce nothing. The default is ``False``. diff --git a/doc/ext/viewcode.rst b/doc/ext/viewcode.rst index ba6c8f86..f2b6c928 100644 --- a/doc/ext/viewcode.rst +++ b/doc/ext/viewcode.rst @@ -16,4 +16,25 @@ descriptions that leads to the source code of the described object. A link back from the source to the description will also be inserted. There are currently no configuration values for this extension; you just need to -add ``'sphinx.ext.viewcode'`` to your :confval:`extensions` value for it to work. +add ``'sphinx.ext.viewcode'`` to your :confval:`extensions` value for it to +work. + +There is also an additional config value: + +.. confval:: viewcode_import + + If this is ``True``, viewcode extension will follow alias objects that + imported from another module such as functions, classes and attributes. + As side effects, this option + else they produce nothing. The default is ``True``. + + .. warning:: + + :confval:`viewcode_import` **imports** the modules to be followed real + location. If any modules have side effects on import, these will be + executed by ``viewcode`` when ``sphinx-build`` is run. + + If you document scripts (as opposed to library modules), make sure their + main routine is protected by a ``if __name__ == '__main__'`` condition. + + .. versionadded:: 1.3 diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst index 0321f5e5..d0d49286 100644 --- a/doc/extdev/appapi.rst +++ b/doc/extdev/appapi.rst @@ -82,16 +82,31 @@ package. Register an event called *name*. This is needed to be able to emit it. +.. method:: Sphinx.set_translator(name, translator_class) + + Register or override a Docutils translator class. This is used to register + a custom output translator or to replace a builtin translator. + This allows extensions to use custom translator and define custom + nodes for the translator (see :meth:`add_node`). + + This is a API version of :confval:`html_translator_class` for all other + builders. Note that if :confval:`html_translator_class` is specified and + this API is called for html related builders, API overriding takes + precedence. + + .. versionadded:: 1.3 + .. method:: Sphinx.add_node(node, **kwds) Register a Docutils node class. This is necessary for Docutils internals. It may also be used in the future to validate nodes in the parsed documents. Node visitor functions for the Sphinx HTML, LaTeX, text and manpage writers - can be given as keyword arguments: the keyword must be one or more of - ``'html'``, ``'latex'``, ``'text'``, ``'man'``, ``'texinfo'``, the value a - 2-tuple of ``(visit, depart)`` methods. ``depart`` can be ``None`` if the - ``visit`` function raises :exc:`docutils.nodes.SkipNode`. Example: + can be given as keyword arguments: the keyword should be one or more of + ``'html'``, ``'latex'``, ``'text'``, ``'man'``, ``'texinfo'`` or any other + supported translators, the value a 2-tuple of ``(visit, depart)`` methods. + ``depart`` can be ``None`` if the ``visit`` function raises + :exc:`docutils.nodes.SkipNode`. Example: .. code-block:: python @@ -131,8 +146,8 @@ package. The directive class must inherit from the class ``docutils.parsers.rst.Directive``. - For example, the (already existing) :rst:dir:`literalinclude` directive would be - added like this: + For example, the (already existing) :rst:dir:`literalinclude` directive would + be added like this: .. code-block:: python @@ -212,10 +227,13 @@ package. .. index:: pair: function; directive The reference node will be of class ``literal`` (so it will be rendered in a - proportional font, as appropriate for code) unless you give the *ref_nodeclass* - argument, which must be a docutils node class (most useful are - ``docutils.nodes.emphasis`` or ``docutils.nodes.strong`` -- you can also use - ``docutils.nodes.generated`` if you want no further text decoration). + proportional font, as appropriate for code) unless you give the + *ref_nodeclass* argument, which must be a docutils node class. Most useful + are ``docutils.nodes.emphasis`` or ``docutils.nodes.strong`` -- you can also + use ``docutils.nodes.generated`` if you want no further text decoration. If + the text should be treated as literal (e.g. no smart quote replacement), but + not have typewriter styling, use ``sphinx.addnodes.literal_emphasis`` or + ``sphinx.addnodes.literal_strong``. For the role content, you have the same syntactical possibilities as for standard Sphinx roles (see :ref:`xref-syntax`). @@ -229,8 +247,8 @@ package. directive it generates must be empty, and will produce no output. That means that you can add semantic targets to your sources, and refer to - them using custom roles instead of generic ones (like :rst:role:`ref`). Example - call:: + them using custom roles instead of generic ones (like :rst:role:`ref`). + Example call:: app.add_crossref_type('topic', 'topic', 'single: %s', docutils.nodes.emphasis) @@ -270,6 +288,18 @@ package. .. versionadded:: 1.0 +.. method:: Sphinx.add_latex_package(packagename, options=None) + + Add *packagename* to the list of packages that LaTeX source code will include. + If you provide *options*, it will be taken to `\usepackage` declaration. + + .. code-block:: python + + app.add_latex_package('mypackage') # => \usepackage{mypackage} + app.add_latex_package('mypackage', 'foo,bar') # => \usepackage[foo,bar]{mypackage} + + .. versionadded:: 1.3 + .. method:: Sphinx.add_lexer(alias, lexer) Use *lexer*, which must be an instance of a Pygments lexer class, to @@ -419,6 +449,19 @@ handlers to the events. Example: .. versionadded:: 0.5 +.. event:: env-before-read-docs (app, env, docnames) + + Emitted after the environment has determined the list of all added and + changed files and just before it reads them. It allows extension authors to + reorder the list of docnames (*inplace*) before processing, or add more + docnames that Sphinx did not consider changed (but never add any docnames + that are not in ``env.found_docs``). + + You can also remove document names; do this with caution since it will make + Sphinx treat changed files as unchanged. + + .. versionadded:: 1.3 + .. event:: source-read (app, docname, source) Emitted when a source file has been read. The *source* argument is a list @@ -462,6 +505,26 @@ handlers to the events. Example: Here is the place to replace custom nodes that don't have visitor methods in the writers, so that they don't cause errors when the writers encounter them. +.. event:: env-merge-info (env, docnames, other) + + This event is only emitted when parallel reading of documents is enabled. It + is emitted once for every subprocess that has read some documents. + + You must handle this event in an extension that stores data in the + environment in a custom location. Otherwise the environment in the main + process will not be aware of the information stored in the subprocess. + + *other* is the environment object from the subprocess, *env* is the + environment from the main process. *docnames* is a set of document names + that have been read in the subprocess. + + For a sample of how to deal with this event, look at the standard + ``sphinx.ext.todo`` extension. The implementation is often similar to that + of :event:`env-purge-doc`, only that information is not removed, but added to + the main environment from the other environment. + + .. versionadded:: 1.3 + .. event:: env-updated (app, env) Emitted when the :meth:`update` method of the build environment has diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst index b76928c0..5144c5f8 100644 --- a/doc/extdev/index.rst +++ b/doc/extdev/index.rst @@ -22,6 +22,28 @@ The configuration file itself can be treated as an extension if it contains a ``setup()`` function. All other extensions to load must be listed in the :confval:`extensions` configuration value. +Extension metadata +------------------ + +.. versionadded:: 1.3 + +The ``setup()`` function can return a dictionary. This is treated by Sphinx +as metadata of the extension. Metadata keys currently recognized are: + +* ``'version'``: a string that identifies the extension version. It is used for + extension version requirement checking (see :confval:`needs_extensions`) and + informational purposes. If not given, ``"unknown version"`` is substituted. +* ``'parallel_read_safe'``: a boolean that specifies if parallel reading of + source files can be used when the extension is loaded. It defaults to + ``False``, i.e. you have to explicitly specify your extension to be + parallel-read-safe after checking that it is. +* ``'parallel_write_safe'``: a boolean that specifies if parallel writing of + output files can be used when the extension is loaded. Since extensions + usually don't negatively influence the process, this defaults to ``True``. + +APIs used for writing extensions +-------------------------------- + .. toctree:: tutorial diff --git a/doc/extdev/tutorial.rst b/doc/extdev/tutorial.rst index a03d6e08..e7912406 100644 --- a/doc/extdev/tutorial.rst +++ b/doc/extdev/tutorial.rst @@ -45,7 +45,7 @@ extension. These are: parsed documents into an output format, or otherwise process them (e.g. check external links). - If you have the application object, the environment is available as + If you have the application object, the builder is available as ``app.builder``. **Config** @@ -162,6 +162,8 @@ new Python module called :file:`todo.py` and add the setup function:: app.connect('doctree-resolved', process_todo_nodes) app.connect('env-purge-doc', purge_todos) + return {'version': '0.1'} # identifies the version of our extension + The calls in this function refer to classes and functions not yet written. What the individual calls do is the following: diff --git a/doc/extensions.rst b/doc/extensions.rst index b2adbc1a..b0d98e38 100644 --- a/doc/extensions.rst +++ b/doc/extensions.rst @@ -31,7 +31,7 @@ These extensions are built in and can be activated by respective entries in the ext/extlinks ext/viewcode ext/linkcode - ext/oldcmarkup + ext/napoleon Third-party extensions diff --git a/doc/faq.rst b/doc/faq.rst index 7aa35d1f..7a49aed6 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -10,9 +10,9 @@ How do I... ----------- ... create PDF files without LaTeX? - You can use `rst2pdf <http://rst2pdf.googlecode.com>`_ version 0.12 or greater - which comes with built-in Sphinx integration. See the :ref:`builders` - section for details. + You can use `rst2pdf <http://rst2pdf.googlecode.com>`_ version 0.12 or + greater which comes with built-in Sphinx integration. See the + :ref:`builders` section for details. ... get section numbers? They are automatic in LaTeX output; for HTML, give a ``:numbered:`` option to @@ -32,9 +32,9 @@ How do I... See the :ref:`extension tutorial <exttut>`. ... convert from my existing docs using MoinMoin markup? - The easiest way is to convert to xhtml, then convert `xhtml to reST`_. You'll - still need to mark up classes and such, but the headings and code examples - come through cleanly. + The easiest way is to convert to xhtml, then convert `xhtml to reST`_. + You'll still need to mark up classes and such, but the headings and code + examples come through cleanly. ... create HTML slides from Sphinx documents? See the "Hieroglyph" package at https://github.com/nyergler/hieroglyph. @@ -50,10 +50,11 @@ Using Sphinx with... -------------------- Read the Docs - https://readthedocs.org is a documentation hosting service based around Sphinx. - They will host sphinx documentation, along with supporting a number of other - features including version support, PDF generation, and more. The `Getting - Started <http://read-the-docs.readthedocs.org/en/latest/getting_started.html>`_ + https://readthedocs.org is a documentation hosting service based around + Sphinx. They will host sphinx documentation, along with supporting a number + of other features including version support, PDF generation, and more. The + `Getting Started + <http://read-the-docs.readthedocs.org/en/latest/getting_started.html>`_ guide is a good place to start. Epydoc @@ -70,8 +71,8 @@ SCons PyPI Jannis Leidel wrote a `setuptools command - <https://pypi.python.org/pypi/Sphinx-PyPI-upload>`_ that automatically uploads - Sphinx documentation to the PyPI package documentation area at + <https://pypi.python.org/pypi/Sphinx-PyPI-upload>`_ that automatically + uploads Sphinx documentation to the PyPI package documentation area at http://pythonhosted.org/. GitHub Pages diff --git a/doc/glossary.rst b/doc/glossary.rst index 8bc393eb..3ef1623d 100644 --- a/doc/glossary.rst +++ b/doc/glossary.rst @@ -12,7 +12,7 @@ Glossary use the builder builders that e.g. check for broken links in the documentation, or build coverage information. - See :ref:`builders` for an overview over Sphinx' built-in builders. + See :ref:`builders` for an overview over Sphinx's built-in builders. configuration directory The directory containing :file:`conf.py`. By default, this is the same as @@ -37,11 +37,11 @@ Glossary document name Since reST source files can have different extensions (some people like ``.txt``, some like ``.rst`` -- the extension can be configured with - :confval:`source_suffix`) and different OSes have different path separators, - Sphinx abstracts them: :dfn:`document names` are always relative to the - :term:`source directory`, the extension is stripped, and path separators - are converted to slashes. All values, parameters and such referring to - "documents" expect such document names. + :confval:`source_suffix`) and different OSes have different path + separators, Sphinx abstracts them: :dfn:`document names` are always + relative to the :term:`source directory`, the extension is stripped, and + path separators are converted to slashes. All values, parameters and such + referring to "documents" expect such document names. Examples for document names are ``index``, ``library/zipfile``, or ``reference/datamodel/types``. Note that there is no leading or trailing @@ -70,8 +70,8 @@ Glossary object The basic building block of Sphinx documentation. Every "object - directive" (e.g. :rst:dir:`function` or :rst:dir:`object`) creates such a block; - and most objects can be cross-referenced to. + directive" (e.g. :rst:dir:`function` or :rst:dir:`object`) creates such a + block; and most objects can be cross-referenced to. role A reStructuredText markup element that allows marking a piece of text. diff --git a/doc/install.rst b/doc/install.rst index bf653872..71e37e9c 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -4,7 +4,7 @@ Installing Sphinx ================= Since Sphinx is written in the Python language, you need to install Python -(the required version is at least 2.5) and Sphinx. +(the required version is at least 2.6) and Sphinx. Sphinx packages are available on the `Python Package Index <https://pypi.python.org/pypi/Sphinx>`_. @@ -79,8 +79,8 @@ sidebar and under "Quick Links", click "Windows Installer" to download. .. note:: - Currently, Python offers two major versions, 2.x and 3.x. Sphinx 1.2 can run - under Python 2.5 to 2.7 and 3.1 to 3.3, with the recommended version being + Currently, Python offers two major versions, 2.x and 3.x. Sphinx 1.3 can run + under Python 2.6, 2.7, 3.2, 3.3, with the recommended version being 2.7. This chapter assumes you have installed Python 2.7. Follow the Windows installer for Python. diff --git a/doc/intl.rst b/doc/intl.rst index 3363dc50..c4859d08 100644 --- a/doc/intl.rst +++ b/doc/intl.rst @@ -38,9 +38,9 @@ task to split up paragraphs which are too large as there is no sane automated way to do that. After Sphinx successfully ran the -:class:`~sphinx.builders.gettext.MessageCatalogBuilder` you will find a collection -of ``.pot`` files in your output directory. These are **catalog templates** -and contain messages in your original language *only*. +:class:`~sphinx.builders.gettext.MessageCatalogBuilder` you will find a +collection of ``.pot`` files in your output directory. These are **catalog +templates** and contain messages in your original language *only*. They can be delivered to translators which will transform them to ``.po`` files --- so called **message catalogs** --- containing a mapping from the original @@ -202,10 +202,13 @@ easy to fetch and push translations. .. code-block:: bash - $ tx init --user=<transifex-username> --pass=<transifex-password> + $ tx init Creating .tx folder... Transifex instance [https://www.transifex.com]: ... + Please enter your transifex username: <transifex-username> + Password: <transifex-password> + ... Done. #. Upload pot files to transifex service @@ -285,7 +288,7 @@ There is `sphinx translation page`_ for Sphinx-1.2 documentation. .. rubric:: Footnotes -.. [1] See the `GNU gettext utilites +.. [1] See the `GNU gettext utilities <http://www.gnu.org/software/gettext/manual/gettext.html#Introduction>`_ for details on that software suite. .. [2] Because nobody expects the Spanish Inquisition! diff --git a/doc/intro.rst b/doc/intro.rst index 66d0c58d..a796d937 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -54,8 +54,8 @@ See the :ref:`pertinent section in the FAQ list <usingwith>`. Prerequisites ------------- -Sphinx needs at least **Python 2.5** or **Python 3.1** to run, as well as the -docutils_ and Jinja2_ libraries. Sphinx should work with docutils version 0.7 +Sphinx needs at least **Python 2.6** or **Python 3.2** to run, as well as the +docutils_ and Jinja2_ libraries. Sphinx should work with docutils version 0.10 or some (not broken) SVN trunk snapshot. If you like to have source code highlighting support, you must also install the Pygments_ library. diff --git a/doc/invocation.rst b/doc/invocation.rst index 654921be..3316522a 100644 --- a/doc/invocation.rst +++ b/doc/invocation.rst @@ -1,5 +1,138 @@ +.. default-role:: any + .. _invocation: +Invocation of sphinx-quickstart +=============================== + +The :program:`sphinx-quickstart` script generates a Sphinx documentation set. +It is called like this:: + + $ sphinx-quickstart [options] [projectdir] + +where *projectdir* is the Sphinx documentation set directory in which you want +to place. If you omit *projectdir*, files are generated into current directory +by default. + +The :program:`sphinx-quickstart` script has several options: + +.. program:: sphinx-quickstart + +.. option:: -q, --quiet + + Quiet mode that will skips interactive wizard to specify options. + This option requires `-p`, `-a` and `-v` options. + +.. option:: -h, --help, --version + + Display usage summary or Sphinx version. + + +Structure options +----------------- + +.. option:: --sep + + If specified, separate source and build directories. + +.. option:: --dot=DOT + + Inside the root directory, two more directories will be created; + "_templates" for custom HTML templates and "_static" for custom stylesheets + and other static files. You can enter another prefix (such as ".") to + replace the underscore. + +Project basic options +--------------------- + +.. option:: -p PROJECT, --project=PROJECT + + Project name will be set. (see :confval:`project`). + +.. option:: -a AUTHOR, --author=AUTHOR + + Author names. (see :confval:`copyright`). + +.. option:: -v VERSION + + Version of project. (see :confval:`version`). + +.. option:: -r RELEASE, --release=RELEASE + + Release of project. (see :confval:`release`). + +.. option:: -l LANGUAGE, --language=LANGUAGE + + Document language. (see :confval:`language`). + +.. option:: --suffix=SUFFIX + + Source file suffix. (see :confval:`source_suffix`). + +.. option:: --master=MASTER + + Master document name. (see :confval:`master_doc`). + +.. option:: --epub + + Use epub. + +Extension options +----------------- + +.. option:: --ext-autodoc + + Enable `sphinx.ext.autodoc` extension. + +.. option:: --ext-doctest + + Enable `sphinx.ext.doctest` extension. + +.. option:: --ext-intersphinx + + Enable `sphinx.ext.intersphinx` extension. + +.. option:: --ext-todo + + Enable `sphinx.ext.todo` extension. + +.. option:: --ext-coverage + + Enable `sphinx.ext.coverage` extension. + +.. option:: --ext-pngmath + + Enable `sphinx.ext.pngmath` extension. + +.. option:: --ext-mathjax + + Enable `sphinx.ext.mathjax` extension. + +.. option:: --ext-ifconfig + + Enable `sphinx.ext.ifconfig` extension. + +.. option:: --ext-viewcode + + Enable `sphinx.ext.viewcode` extension. + + +Makefile and Batchfile creation options +--------------------------------------- + +.. option:: --makefile, --no-makefile + + Create (or not create) makefile. + +.. option:: --batchfile, --no-batchfile + + Create (or not create) batchfile + + +.. versionadded:: 1.3 + Add various options for sphinx-quickstart invocation. + + Invocation of sphinx-build ========================== @@ -83,8 +216,8 @@ The :program:`sphinx-build` script has several options: .. option:: -t tag - Define the tag *tag*. This is relevant for :rst:dir:`only` directives that only - include their content if this tag is set. + Define the tag *tag*. This is relevant for :rst:dir:`only` directives that + only include their content if this tag is set. .. versionadded:: 0.6 @@ -124,13 +257,22 @@ The :program:`sphinx-build` script has several options: .. option:: -D setting=value Override a configuration value set in the :file:`conf.py` file. The value - must be a string or dictionary value. For the latter, supply the setting - name and key like this: ``-D latex_elements.docclass=scrartcl``. For boolean - values, use ``0`` or ``1`` as the value. + must be a number, string, list or dictionary value. + + For lists, you can separate elements with a comma like this: ``-D + html_theme_path=path1,path2``. + + For dictionary values, supply the setting name and key like this: + ``-D latex_elements.docclass=scrartcl``. + + For boolean values, use ``0`` or ``1`` as the value. .. versionchanged:: 0.6 The value can now be a dictionary value. + .. versionchanged:: 1.3 + The value can now also be a list value. + .. option:: -A name=value Make the *name* assigned to *value* in the HTML templates. @@ -145,8 +287,7 @@ The :program:`sphinx-build` script has several options: .. option:: -N - Do not emit colored output. (On Windows, colored output is disabled in any - case.) + Do not emit colored output. .. option:: -v diff --git a/doc/man/sphinx-build.rst b/doc/man/sphinx-build.rst index aa1d71c6..13564ff4 100644 --- a/doc/man/sphinx-build.rst +++ b/doc/man/sphinx-build.rst @@ -102,12 +102,14 @@ Options Configuration can only be set with the -D option. -D <setting=value> Override a setting from the configuration file. -t <tag> Define *tag* for use in "only" blocks. --A <name=value> Pass a value into the HTML templates (only for HTML builders). +-A <name=value> Pass a value into the HTML templates (only for HTML + builders). -n Run in nit-picky mode, warn about all missing references. -v Increase verbosity (can be repeated). -N Prevent colored output. -q Quiet operation, just print warnings and errors on stderr. --Q Very quiet operation, don't print anything except for errors. +-Q Very quiet operation, don't print anything except for + errors. -w <file> Write warnings and errors into the given file, in addition to stderr. -W Turn warnings into errors. diff --git a/doc/markup/code.rst b/doc/markup/code.rst index 957774f0..9a503519 100644 --- a/doc/markup/code.rst +++ b/doc/markup/code.rst @@ -36,21 +36,29 @@ installed) and handled in a smart way: highlighted as Python). * The highlighting language can be changed using the ``highlight`` directive, - used as follows:: + used as follows: - .. highlight:: c + .. rst:directive:: .. highlight:: language - This language is used until the next ``highlight`` directive is encountered. + Example:: + + .. highlight:: c + + This language is used until the next ``highlight`` directive is encountered. * For documents that have to show snippets in different languages, there's also a :rst:dir:`code-block` directive that is given the highlighting language - directly:: + directly: + + .. rst:directive:: .. code-block:: language + + Use it like this:: - .. code-block:: ruby + .. code-block:: ruby - Some Ruby code. + Some Ruby code. - The directive's alias name :rst:dir:`sourcecode` works as well. + The directive's alias name :rst:dir:`sourcecode` works as well. * The valid values for the highlighting language are: @@ -79,14 +87,22 @@ option:: This will produce line numbers for all code blocks longer than five lines. -For :rst:dir:`code-block` blocks, a ``linenos`` flag option can be given to switch -on line numbers for the individual block:: +For :rst:dir:`code-block` blocks, a ``linenos`` flag option can be given to +switch on line numbers for the individual block:: .. code-block:: ruby :linenos: Some more Ruby code. +The first line number can be selected with the ``lineno-start`` option. If +present, ``linenos`` is automatically activated as well. + + .. code-block:: ruby + :lineno-start: 10 + + Some more Ruby code, with line numbering starting at 10. + Additionally, an ``emphasize-lines`` option can be given to have Pygments emphasize particular lines:: @@ -102,16 +118,19 @@ emphasize particular lines:: .. versionchanged:: 1.1 ``emphasize-lines`` has been added. +.. versionchanged:: 1.3 + ``lineno-start`` has been added. + Includes ^^^^^^^^ .. rst:directive:: .. literalinclude:: filename - Longer displays of verbatim text may be included by storing the example text in - an external file containing only plain text. The file may be included using the - ``literalinclude`` directive. [1]_ For example, to include the Python source file - :file:`example.py`, use:: + Longer displays of verbatim text may be included by storing the example text + in an external file containing only plain text. The file may be included + using the ``literalinclude`` directive. [1]_ For example, to include the + Python source file :file:`example.py`, use:: .. literalinclude:: example.py @@ -122,10 +141,11 @@ Includes Tabs in the input are expanded if you give a ``tab-width`` option with the desired tab width. - The directive also supports the ``linenos`` flag option to switch on line - numbers, the ``emphasize-lines`` option to emphasize particular lines, and - a ``language`` option to select a language different from the current - file's standard language. Example with options:: + Like :rst:dir:`code-block`, the directive supports the ``linenos`` flag + option to switch on line numbers, the ``lineno-start`` option to select the + first line number, the ``emphasize-lines`` option to emphasize particular + lines, and a ``language`` option to select a language different from the + current file's standard language. Example with options:: .. literalinclude:: example.rb :language: ruby @@ -164,10 +184,24 @@ Includes string option, only lines that precede the first lines containing that string are included. + When specifying particular parts of a file to display, it can be useful to + display exactly which lines are being presented. + This can be done using the ``lineno-match`` option. + You can prepend and/or append a line to the included code, using the ``prepend`` and ``append`` option, respectively. This is useful e.g. for highlighting PHP code that doesn't include the ``<?php``/``?>`` markers. + + If you want to show the diff of the code, you can specify the old + file by giving a ``diff`` option:: + + .. literalinclude:: example.py + :diff: example.py.orig + + This shows the diff between example.py and example.py.orig with unified diff + format. + .. versionadded:: 0.4.3 The ``encoding`` option. .. versionadded:: 0.6 @@ -175,6 +209,44 @@ Includes as well as support for absolute filenames. .. versionadded:: 1.0 The ``prepend`` and ``append`` options, as well as ``tab-width``. + .. versionadded:: 1.3 + The ``diff`` option. + The ``lineno-match`` option. + + +Showing a file name +^^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 1.3 + +A ``caption`` option can be given to show that name before the code block. For +example:: + + .. code-block:: python + :caption: this.py + + print 'Explicit is better than implicit.' + + +:rst:dir:`literalinclude` also supports the ``caption`` option, with the +additional feature that if you leave the value empty, the shown filename will be +exactly the one given as an argument. + + +Dedent +^^^^^^ + +.. versionadded:: 1.3 + +A ``dedent`` option can be given to strip a precedence characters from the code +block. For example:: + + .. literalinclude:: example.rb + :language: ruby + :dedent: 4 + :lines: 10-15 + +:rst:dir:`code-block` also supports the ``dedent`` option. .. rubric:: Footnotes diff --git a/doc/markup/inline.rst b/doc/markup/inline.rst index 69dd832f..6f3ebe1c 100644 --- a/doc/markup/inline.rst +++ b/doc/markup/inline.rst @@ -12,7 +12,9 @@ They are written as ``:rolename:`content```. The default role (```content```) has no special meaning by default. You are free to use it for anything you like, e.g. variable names; use the - :confval:`default_role` config value to set it to a known role. + :confval:`default_role` config value to set it to a known role -- the + :rst:role:`any` role to find anything or the :rst:role:`py:obj` role to find + Python objects are very useful for this. See :ref:`domains` for roles added by domains. @@ -24,7 +26,7 @@ Cross-referencing syntax Cross-references are generated by many semantic interpreted text roles. Basically, you only need to write ``:role:`target```, and a link will be created -to the item named *target* of the type indicated by *role*. The links's text +to the item named *target* of the type indicated by *role*. The link's text will be the same as *target*. There are some additional facilities, however, that make cross-referencing roles @@ -38,12 +40,57 @@ more versatile: * If you prefix the content with ``~``, the link text will only be the last component of the target. For example, ``:py:meth:`~Queue.Queue.get``` will - refer to ``Queue.Queue.get`` but only display ``get`` as the link text. + refer to ``Queue.Queue.get`` but only display ``get`` as the link text. This + does not work with all cross-reference roles, but is domain specific. In HTML output, the link's ``title`` attribute (that is e.g. shown as a tool-tip on mouse-hover) will always be the full target name. +.. _any-role: + +Cross-referencing anything +-------------------------- + +.. rst:role:: any + + .. versionadded:: 1.3 + + This convenience role tries to do its best to find a valid target for its + reference text. + + * First, it tries standard cross-reference targets that would be referenced + by :rst:role:`doc`, :rst:role:`ref` or :rst:role:`option`. + + Custom objects added to the standard domain by extensions (see + :meth:`.add_object_type`) are also searched. + + * Then, it looks for objects (targets) in all loaded domains. It is up to + the domains how specific a match must be. For example, in the Python + domain a reference of ``:any:`Builder``` would match the + ``sphinx.builders.Builder`` class. + + If none or multiple targets are found, a warning will be emitted. In the + case of multiple targets, you can change "any" to a specific role. + + This role is a good candidate for setting :confval:`default_role`. If you + do, you can write cross-references without a lot of markup overhead. For + example, in this Python function documentation :: + + .. function:: install() + + This function installs a `handler` for every signal known by the + `signal` module. See the section `about-signals` for more information. + + there could be references to a glossary term (usually ``:term:`handler```), a + Python module (usually ``:py:mod:`signal``` or ``:mod:`signal```) and a + section (usually ``:ref:`about-signals```). + + The :rst:role:`any` role also works together with the + :mod:`~sphinx.ext.intersphinx` extension: when no local cross-reference is + found, all object types of intersphinx inventories are also searched. + + Cross-referencing objects ------------------------- @@ -102,9 +149,10 @@ Cross-referencing arbitrary locations to, but you must give the link an explicit title, using this syntax: ``:ref:`Link title <label-name>```. - Using :rst:role:`ref` is advised over standard reStructuredText links to sections - (like ```Section title`_``) because it works across files, when section - headings are changed, and for all builders that support cross-references. + Using :rst:role:`ref` is advised over standard reStructuredText links to + sections (like ```Section title`_``) because it works across files, when + section headings are changed, and for all builders that support + cross-references. Cross-referencing documents @@ -153,6 +201,24 @@ Referencing downloadable files suitable link generated to it. +Cross-referencing figures by figure number +------------------------------------------ + +.. versionadded:: 1.3 + +.. rst:role:: numref + + Link to the specified figures, tables and code-blocks; the standard reST + labels are used. When you use this role, it will insert a reference to the + figure with link text by its figure number like "Fig. 1.1". + + If an explicit link text is given (like usual: ``:doc:`Image of Sphinx (Fig. + #) <my-figure>```), the link caption will be the title of the reference. + As a special character, `#` will be replaced to figure number. + + If :confval:`numfig` is ``False``, figures are not numbered. + so this role inserts not a reference but labels or link text. + Cross-referencing other items of interest ----------------------------------------- @@ -349,8 +415,8 @@ the standard reST markup for that purpose. Substitutions ~~~~~~~~~~~~~ -The documentation system provides three substitutions that are defined by default. -They are set in the build configuration file. +The documentation system provides three substitutions that are defined by +default. They are set in the build configuration file. .. describe:: |release| diff --git a/doc/markup/misc.rst b/doc/markup/misc.rst index 5a391d02..fd31480a 100644 --- a/doc/markup/misc.rst +++ b/doc/markup/misc.rst @@ -52,16 +52,16 @@ Meta-information markup By default, this markup isn't reflected in the output in any way (it helps keep track of contributions), but you can set the configuration value - :confval:`show_authors` to True to make them produce a paragraph in the + :confval:`show_authors` to ``True`` to make them produce a paragraph in the output. .. rst:directive:: .. codeauthor:: name <email> - The :rst:dir:`codeauthor` directive, which can appear multiple times, names the - authors of the described code, just like :rst:dir:`sectionauthor` names the - author(s) of a piece of documentation. It too only produces output if the - :confval:`show_authors` configuration value is True. + The :rst:dir:`codeauthor` directive, which can appear multiple times, names + the authors of the described code, just like :rst:dir:`sectionauthor` names + the author(s) of a piece of documentation. It too only produces output if + the :confval:`show_authors` configuration value is ``True``. Index-generating markup @@ -189,6 +189,14 @@ Including content based on tags These standard tags are set *after* the configuration file is read, so they are not available there. + All tags must follow the standard Python identifier syntax as set out in + the `Identifiers and keywords + <https://docs.python.org/reference/lexical_analysis.html#identifiers>`_ + documentation. That is, a tag expression may only consist of tags that + conform to the syntax of Python variables. In ASCII, this consists of the + uppercase and lowercase letters ``A`` through ``Z``, the underscore ``_`` + and, except for the first character, the digits ``0`` through ``9``. + .. versionadded:: 0.6 .. versionchanged:: 1.2 Added the name of the builder and the prefixes. diff --git a/doc/markup/para.rst b/doc/markup/para.rst index b532bc63..c6a49b15 100644 --- a/doc/markup/para.rst +++ b/doc/markup/para.rst @@ -70,12 +70,12 @@ units as well as normal text: external documents. These lists are created using the :rst:dir:`seealso` directive. - The :rst:dir:`seealso` directive is typically placed in a section just before any - sub-sections. For the HTML output, it is shown boxed off from the main flow - of the text. + The :rst:dir:`seealso` directive is typically placed in a section just before + any subsections. For the HTML output, it is shown boxed off from the main + flow of the text. - The content of the :rst:dir:`seealso` directive should be a reST definition list. - Example:: + The content of the :rst:dir:`seealso` directive should be a reST definition + list. Example:: .. seealso:: @@ -206,8 +206,8 @@ the definition of the symbol. There is this directive: continuation line must begin with a colon placed at the same column as in the first line. - The argument to :rst:dir:`productionlist` serves to distinguish different sets of - production lists that belong to different grammars. + The argument to :rst:dir:`productionlist` serves to distinguish different + sets of production lists that belong to different grammars. Blank lines are not allowed within ``productionlist`` directive arguments. diff --git a/doc/more.png b/doc/more.png Binary files differindex 3eb7b05c..a27a0fcb 100644 --- a/doc/more.png +++ b/doc/more.png diff --git a/doc/pythonorg.png b/doc/pythonorg.png Binary files differindex 83b54df0..32f0787d 100644 --- a/doc/pythonorg.png +++ b/doc/pythonorg.png diff --git a/doc/rest.rst b/doc/rest.rst index b5efbf98..c6a4ada0 100644 --- a/doc/rest.rst +++ b/doc/rest.rst @@ -312,7 +312,7 @@ Docutils supports the following directives: - :dudir:`default-role` (set a new default role) - :dudir:`role` (create a new role) - Since these are only per-file, better use Sphinx' facilities for setting the + Since these are only per-file, better use Sphinx's facilities for setting the :confval:`default_role`. Do *not* use the directives :dudir:`sectnum`, :dudir:`header` and @@ -485,5 +485,6 @@ There are some problems one commonly runs into while authoring reST documents: .. rubric:: Footnotes -.. [1] When the default domain contains a :rst:dir:`class` directive, this directive - will be shadowed. Therefore, Sphinx re-exports it as :rst:dir:`rst-class`. +.. [1] When the default domain contains a :rst:dir:`class` directive, this + directive will be shadowed. Therefore, Sphinx re-exports it as + :rst:dir:`rst-class`. diff --git a/doc/templating.rst b/doc/templating.rst index b9561b69..fde00ef8 100644 --- a/doc/templating.rst +++ b/doc/templating.rst @@ -11,8 +11,8 @@ anyone having used Django will already be familiar with it. It also has excellent documentation for those who need to make themselves familiar with it. -Do I need to use Sphinx' templates to produce HTML? ---------------------------------------------------- +Do I need to use Sphinx's templates to produce HTML? +---------------------------------------------------- No. You have several other options: @@ -50,7 +50,7 @@ A template contains **variables**, which are replaced with values when the template is evaluated, **tags**, which control the logic of the template and **blocks** which are used for template inheritance. -Sphinx' *basic* theme provides base templates with a couple of blocks it will +Sphinx's *basic* theme provides base templates with a couple of blocks it will fill with data. These are located in the :file:`themes/basic` subdirectory of the Sphinx installation directory, and used by all builtin Sphinx themes. Templates with the same name in the :confval:`templates_path` override templates @@ -273,7 +273,7 @@ in the future. .. data:: has_source True if the reST document sources are copied (if :confval:`html_copy_source` - is true). + is ``True``). .. data:: last_updated @@ -333,7 +333,7 @@ in the future. .. data:: show_source - True if :confval:`html_show_sourcelink` is true. + True if :confval:`html_show_sourcelink` is ``True``. .. data:: sphinx_version @@ -372,7 +372,7 @@ are in HTML form), these variables are also available: .. data:: sourcename The name of the copied source file for the current document. This is only - nonempty if the :confval:`html_copy_source` value is true. + nonempty if the :confval:`html_copy_source` value is ``True``. .. data:: toc @@ -384,14 +384,14 @@ are in HTML form), these variables are also available: A callable yielding the global TOC tree containing the current page, rendered as HTML bullet lists. Optional keyword arguments: - * ``collapse`` (true by default): if true, all TOC entries that are not + * ``collapse`` (``True`` by default): if true, all TOC entries that are not ancestors of the current page are collapsed * ``maxdepth`` (defaults to the max depth selected in the toctree directive): the maximum depth of the tree; set it to ``-1`` to allow unlimited depth - * ``titles_only`` (false by default): if true, put only toplevel document + * ``titles_only`` (``False`` by default): if true, put only toplevel document titles in the tree - * ``includehidden`` (false by default): if true, the TOC tree will also + * ``includehidden`` (``False`` by default): if true, the TOC tree will also contain hidden entries. diff --git a/doc/themes/agogo.png b/doc/themes/agogo.png Binary files differindex d29aa45c..453a1f7d 100644 --- a/doc/themes/agogo.png +++ b/doc/themes/agogo.png diff --git a/doc/themes/bizstyle.png b/doc/themes/bizstyle.png Binary files differnew file mode 100644 index 00000000..4deae9a7 --- /dev/null +++ b/doc/themes/bizstyle.png diff --git a/doc/themes/default.png b/doc/themes/default.png Binary files differindex 93d8526c..6989ebe9 100644 --- a/doc/themes/default.png +++ b/doc/themes/default.png diff --git a/doc/themes/fullsize/agogo.png b/doc/themes/fullsize/agogo.png Binary files differindex 93fadfcb..bfdba3a1 100644 --- a/doc/themes/fullsize/agogo.png +++ b/doc/themes/fullsize/agogo.png diff --git a/doc/themes/fullsize/bizstyle.png b/doc/themes/fullsize/bizstyle.png Binary files differnew file mode 100644 index 00000000..d917e2ff --- /dev/null +++ b/doc/themes/fullsize/bizstyle.png diff --git a/doc/themes/fullsize/default.png b/doc/themes/fullsize/default.png Binary files differindex b6af8bc3..9c00f689 100644 --- a/doc/themes/fullsize/default.png +++ b/doc/themes/fullsize/default.png diff --git a/doc/themes/fullsize/haiku.png b/doc/themes/fullsize/haiku.png Binary files differindex 1590da5d..8d807f4e 100644 --- a/doc/themes/fullsize/haiku.png +++ b/doc/themes/fullsize/haiku.png diff --git a/doc/themes/fullsize/nature.png b/doc/themes/fullsize/nature.png Binary files differindex d42957e3..02d8743b 100644 --- a/doc/themes/fullsize/nature.png +++ b/doc/themes/fullsize/nature.png diff --git a/doc/themes/fullsize/pyramid.png b/doc/themes/fullsize/pyramid.png Binary files differindex 429a8b7e..961cb896 100644 --- a/doc/themes/fullsize/pyramid.png +++ b/doc/themes/fullsize/pyramid.png diff --git a/doc/themes/fullsize/scrolls.png b/doc/themes/fullsize/scrolls.png Binary files differindex 7d46f7ed..4e5c45f2 100644 --- a/doc/themes/fullsize/scrolls.png +++ b/doc/themes/fullsize/scrolls.png diff --git a/doc/themes/fullsize/sphinxdoc.png b/doc/themes/fullsize/sphinxdoc.png Binary files differindex 722fb900..b7463345 100644 --- a/doc/themes/fullsize/sphinxdoc.png +++ b/doc/themes/fullsize/sphinxdoc.png diff --git a/doc/themes/fullsize/traditional.png b/doc/themes/fullsize/traditional.png Binary files differindex 103fd3ca..da69efe1 100644 --- a/doc/themes/fullsize/traditional.png +++ b/doc/themes/fullsize/traditional.png diff --git a/doc/themes/haiku.png b/doc/themes/haiku.png Binary files differindex a8ae8557..78a2570c 100644 --- a/doc/themes/haiku.png +++ b/doc/themes/haiku.png diff --git a/doc/themes/nature.png b/doc/themes/nature.png Binary files differindex 3d4f587f..cbe773d5 100644 --- a/doc/themes/nature.png +++ b/doc/themes/nature.png diff --git a/doc/themes/pyramid.png b/doc/themes/pyramid.png Binary files differindex b16095c9..eb13cd5f 100644 --- a/doc/themes/pyramid.png +++ b/doc/themes/pyramid.png diff --git a/doc/themes/scrolls.png b/doc/themes/scrolls.png Binary files differindex 8073c10e..30ccc8d4 100644 --- a/doc/themes/scrolls.png +++ b/doc/themes/scrolls.png diff --git a/doc/themes/sphinxdoc.png b/doc/themes/sphinxdoc.png Binary files differindex f4b59ecd..31512d8d 100644 --- a/doc/themes/sphinxdoc.png +++ b/doc/themes/sphinxdoc.png diff --git a/doc/themes/traditional.png b/doc/themes/traditional.png Binary files differindex 4ad2b5ce..5ff44f86 100644 --- a/doc/themes/traditional.png +++ b/doc/themes/traditional.png diff --git a/doc/theming.rst b/doc/theming.rst index 73ec9f27..0a2d726d 100644 --- a/doc/theming.rst +++ b/doc/theming.rst @@ -102,6 +102,10 @@ Builtin themes | | | | *haiku* | *pyramid* | +--------------------+--------------------+ +| |bizstyle| | | +| | | +| *bizstyle* | | ++--------------------+--------------------+ .. |default| image:: themes/default.png .. |sphinxdoc| image:: themes/sphinxdoc.png @@ -111,6 +115,7 @@ Builtin themes .. |nature| image:: themes/nature.png .. |haiku| image:: themes/haiku.png .. |pyramid| image:: themes/pyramid.png +.. |bizstyle| image:: themes/bizstyle.png Sphinx comes with a selection of themes to choose from. @@ -122,7 +127,7 @@ These themes are: these options (which are inherited by the other themes): - **nosidebar** (true or false): Don't include the sidebar. Defaults to - false. + ``False``. - **sidebarwidth** (an integer): Width of the sidebar in pixels. (Do not include ``px`` in the value.) Defaults to 230 pixels. @@ -132,18 +137,18 @@ These themes are: options: - **rightsidebar** (true or false): Put the sidebar on the right side. - Defaults to false. + Defaults to ``False``. - **stickysidebar** (true or false): Make the sidebar "fixed" so that it doesn't scroll out of view for long body content. This may not work well - with all browsers. Defaults to false. + with all browsers. Defaults to ``False``. - **collapsiblesidebar** (true or false): Add an *experimental* JavaScript snippet that makes the sidebar collapsible via a button on its side. - *Doesn't work with "stickysidebar".* Defaults to false. + *Doesn't work with "stickysidebar".* Defaults to ``False``. - **externalrefs** (true or false): Display external links differently from - internal links. Defaults to false. + internal links. Defaults to ``False``. There are also various color and font options that can change the color scheme without having to write a custom stylesheet: @@ -152,7 +157,7 @@ These themes are: - **footertextcolor** (CSS color): Text color for the footer line. - **sidebarbgcolor** (CSS color): Background color for the sidebar. - **sidebarbtncolor** (CSS color): Background color for the sidebar collapse - button (used when *collapsiblesidebar* is true). + button (used when *collapsiblesidebar* is ``True``). - **sidebartextcolor** (CSS color): Text color for the sidebar. - **sidebarlinkcolor** (CSS color): Link color for the sidebar. - **relbarbgcolor** (CSS color): Background color for the relation bar. @@ -218,10 +223,10 @@ These themes are: <http://www.haiku-os.org/docs/userguide/en/contents.html>`_. The following options are supported: - - **full_logo** (true or false, default false): If this is true, the header - will only show the :confval:`html_logo`. Use this for large logos. If this - is false, the logo (if present) will be shown floating right, and the - documentation title will be put in the header. + - **full_logo** (true or false, default ``False``): If this is true, the + header will only show the :confval:`html_logo`. Use this for large logos. + If this is false, the logo (if present) will be shown floating right, and + the documentation title will be put in the header. - **textcolor**, **headingcolor**, **linkcolor**, **visitedlinkcolor**, **hoverlinkcolor** (CSS colors): Colors for various body elements. @@ -232,10 +237,20 @@ These themes are: space which is a sparse resource on ebook readers. The following options are supported: - - **relbar1** (true or false, default true): If this is true, the + - **relbar1** (true or false, default ``True``): If this is true, the `relbar1` block is inserted in the epub output, otherwise it is omitted. - - **footer** (true or false, default true): If this is true, the - `footer` block is inserted in the epub output, otherwise it is ommitted. + - **footer** (true or false, default ``True``): If this is true, the + `footer` block is inserted in the epub output, otherwise it is omitted. + +- **bizstyle** -- A simple bluish theme. The following options are supported + beyond *nosidebar* and *sidebarwidth*: + + - **rightsidebar** (true or false): Put the sidebar on the right side. + Defaults to ``False``. + +.. versionadded:: 1.3 + 'bizstyle' theme. + Creating themes --------------- @@ -318,4 +333,3 @@ is built with the default theme, the output directory will contain a .. [1] It is not an executable Python file, as opposed to :file:`conf.py`, because that would pose an unnecessary security risk if themes are shared. - diff --git a/doc/translation.png b/doc/translation.png Binary files differindex aa368b67..347e287f 100644 --- a/doc/translation.png +++ b/doc/translation.png diff --git a/doc/tutorial.rst b/doc/tutorial.rst index cae4c8db..0a12a27a 100644 --- a/doc/tutorial.rst +++ b/doc/tutorial.rst @@ -10,6 +10,15 @@ The green arrows designate "more info" links leading to advanced sections about the described task. +Install Sphinx +-------------- + +Install Sphinx, either from a distribution package or from +`PyPI <https://pypi.python.org/pypi/Sphinx>`_ with :: + + $ pip install Sphinx + + Setting up the documentation sources ------------------------------------ @@ -138,7 +147,7 @@ an argument to see which targets are available. Documenting objects ------------------- -One of Sphinx' main objectives is easy documentation of :dfn:`objects` (in a +One of Sphinx's main objectives is easy documentation of :dfn:`objects` (in a very general sense) in any :dfn:`domain`. A domain is a collection of object types that belong together, complete with markup to create and reference descriptions of these objects. @@ -200,7 +209,7 @@ Earlier we mentioned that the :file:`conf.py` file controls how Sphinx processes your documents. In that file, which is executed as a Python source file, you assign configuration values. For advanced users: since it is executed by Sphinx, you can do non-trivial tasks in it, like extending :data:`sys.path` or -importing a module to find out the version your are documenting. +importing a module to find out the version you are documenting. The config values that you probably want to change are already put into the :file:`conf.py` by :program:`sphinx-quickstart` and initially commented out @@ -300,7 +309,7 @@ More topics to be covered .. rubric:: Footnotes -.. [#] This is the usual lay-out. However, :file:`conf.py` can also live in +.. [#] This is the usual layout. However, :file:`conf.py` can also live in another directory, the :term:`configuration directory`. See :ref:`invocation`. diff --git a/doc/web/quickstart.rst b/doc/web/quickstart.rst index 1bcd217e..996942db 100644 --- a/doc/web/quickstart.rst +++ b/doc/web/quickstart.rst @@ -45,7 +45,7 @@ by creating a :class:`~.WebSupport` object for your application:: search='xapian') You'll only need one of these for each set of documentation you will be working -with. You can then call it's :meth:`~.WebSupport.get_document` method to access +with. You can then call its :meth:`~.WebSupport.get_document` method to access individual documents:: contents = support.get_document('contents') @@ -56,8 +56,8 @@ This will return a dictionary containing the following items: * **sidebar**: The sidebar of the document as HTML * **relbar**: A div containing links to related documents * **title**: The title of the document -* **css**: Links to css files used by Sphinx -* **js**: Javascript containing comment options +* **css**: Links to CSS files used by Sphinx +* **script**: JavaScript containing comment options This dict can then be used as context for templates. The goal is to be easy to integrate with your existing templating system. An example using `Jinja2 @@ -77,9 +77,9 @@ integrate with your existing templating system. An example using `Jinja2 <link rel="stylesheet" href="/static/websupport-custom.css" type="text/css"> {% endblock %} - {%- block js %} + {%- block script %} {{ super() }} - {{ document.js|safe }} + {{ document.script|safe }} {%- endblock %} {%- block relbar %} @@ -109,8 +109,8 @@ must update the websupport package's data:: support.update_username(old_username, new_username) *username* should be a unique string which identifies a user, and *moderator* -should be a boolean representing whether the user has moderation privilieges. -The default value for *moderator* is *False*. +should be a boolean representing whether the user has moderation privileges. +The default value for *moderator* is ``False``. An example `Flask <http://flask.pocoo.org/>`_ function that checks whether a user is logged in and then retrieves a document is:: |
