diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/_static/conf.py.txt | 7 | ||||
| -rw-r--r-- | doc/builders.rst | 29 | ||||
| -rw-r--r-- | doc/config.rst | 152 | ||||
| -rw-r--r-- | doc/contents.rst | 1 | ||||
| -rw-r--r-- | doc/develop.rst | 8 | ||||
| -rw-r--r-- | doc/domains.rst | 14 | ||||
| -rw-r--r-- | doc/ext/doctest.rst | 15 | ||||
| -rw-r--r-- | doc/ext/example_google.py | 2 | ||||
| -rw-r--r-- | doc/ext/example_numpy.py | 2 | ||||
| -rw-r--r-- | doc/ext/graphviz.rst | 17 | ||||
| -rw-r--r-- | doc/extdev/appapi.rst | 20 | ||||
| -rw-r--r-- | doc/extdev/collectorapi.rst | 9 | ||||
| -rw-r--r-- | doc/extdev/index.rst | 2 | ||||
| -rw-r--r-- | doc/extdev/logging.rst | 77 | ||||
| -rw-r--r-- | doc/extdev/nodes.rst | 1 | ||||
| -rw-r--r-- | doc/extdev/tutorial.rst | 25 | ||||
| -rw-r--r-- | doc/faq.rst | 2 | ||||
| -rw-r--r-- | doc/intl.rst | 2 | ||||
| -rw-r--r-- | doc/invocation.rst | 2 | ||||
| -rw-r--r-- | doc/latex.rst | 32 | ||||
| -rw-r--r-- | doc/markup/code.rst | 18 | ||||
| -rw-r--r-- | doc/markup/misc.rst | 91 | ||||
| -rw-r--r-- | doc/markup/toctree.rst | 2 | ||||
| -rw-r--r-- | doc/setuptools.rst | 178 | ||||
| -rw-r--r-- | doc/templating.rst | 64 | ||||
| -rw-r--r-- | doc/tutorial.rst | 1 |
26 files changed, 551 insertions, 222 deletions
diff --git a/doc/_static/conf.py.txt b/doc/_static/conf.py.txt index ab54f15b8..be0c846db 100644 --- a/doc/_static/conf.py.txt +++ b/doc/_static/conf.py.txt @@ -79,7 +79,7 @@ language = None # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -# This patterns also effect to html_static_path and html_extra_path +# These patterns also affect html_static_path and html_extra_path exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] # The reST default role (used for this markup: `text`) to use for all @@ -268,11 +268,6 @@ latex_documents = [ # # latex_logo = None -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -# -# latex_use_parts = False - # If true, show page references after internal links. # # latex_show_pagerefs = False diff --git a/doc/builders.rst b/doc/builders.rst index f3bacb139..2d17abc7d 100644 --- a/doc/builders.rst +++ b/doc/builders.rst @@ -178,12 +178,29 @@ The builder's "name" must be given to the **-b** command-line option of .. note:: The produced LaTeX file uses several LaTeX packages that may not be - present in a "minimal" TeX distribution installation. For TeXLive, - the following packages need to be installed: - - * latex-recommended - * latex-extra - * fonts-recommended + present in a "minimal" TeX distribution installation. For example, on + Ubuntu, the following packages need to be installed for successful PDF + builds: + + * texlive-latex-recommended + * texlive-fonts-recommended + * texlive-latex-extra + * latexmk (for ``make latexpdf``) + + Sphinx will use ``xcolor.sty`` if present: recent Ubuntu distributions + have ``xcolor.sty`` included in latex-recommended, earlier ones have it + in latex-xcolor. Unicode engines will need texlive-luatex or + texlive-xetex. + + The testing of Sphinx LaTeX is done on Ubuntu trusty with the above + mentioned packages, which are from a TeXLive 2013 snapshot dated + February 2014. + + .. versionchanged:: 1.6 + Formerly, testing had been done for some years on Ubuntu precise + (based on TeXLive 2009). + .. versionchanged:: 1.6 + Use of ``latexmk`` on GNU/Linux or Mac OS X. .. autoattribute:: name diff --git a/doc/config.rst b/doc/config.rst index 5098c2fca..15a9a339b 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -226,8 +226,10 @@ General configuration * app.add_role * app.add_generic_role * app.add_source_parser + * download.not_readable * image.data_uri * image.nonlocal_uri + * image.not_readable * ref.term * ref.ref * ref.numref @@ -382,18 +384,6 @@ Project information %Y'`` (or, if translation is enabled with :confval:`language`, an equivalent format for the selected locale). - .. versionchanged:: 1.4 - - Format specification was changed from strftime to Locale Data Markup - Language. strftime format is also supported for backward compatibility - until Sphinx-1.5. - - .. versionchanged:: 1.4.1 - - Format specification was changed again from Locale Data Markup Language - to strftime. LDML format is also supported for backward compatibility - until Sphinx-1.5. - .. confval:: highlight_language The default language to highlight source code in. The default is @@ -769,19 +759,6 @@ that use Sphinx's HTMLWriter class. The empty string is equivalent to ``'%b %d, %Y'`` (or a locale-dependent equivalent). - .. versionchanged:: 1.4 - - Format specification was changed from strftime to Locale Data Markup - Language. strftime format is also supported for backward compatibility - until Sphinx-1.5. - - .. versionchanged:: 1.4.1 - - Format specification was changed again from Locale Data Markup Language - to strftime. LDML format is also supported for backward compatibility - until Sphinx-1.5. - - .. confval:: html_use_smartypants If true, `SmartyPants <http://daringfireball.net/projects/smartypants/>`_ @@ -881,13 +858,6 @@ that use Sphinx's HTMLWriter class. .. versionadded:: 1.0 -.. confval:: html_use_modindex - - If true, add a module index to the HTML documents. Default is ``True``. - - .. deprecated:: 1.0 - Use :confval:`html_domain_indices`. - .. confval:: html_use_index If true, add an index to the HTML documents. Default is ``True``. @@ -950,20 +920,6 @@ that use Sphinx's HTMLWriter class. .. versionadded:: 0.6 -.. confval:: html_translator_class - - A string with the fully-qualified name of a HTML Translator class, that is, a - 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` - - .. deprecated:: 1.5 - - Implement your translator as extension and use `Sphinx.set_translator` - instead. - .. confval:: html_show_copyright If true, "(C) Copyright ..." is shown in the HTML footer. Default is @@ -1133,6 +1089,11 @@ that use Sphinx's HTMLWriter class. Output file base name for HTML help builder. Default is ``'pydoc'``. +.. confval:: html_experimental_html5_writer + + Output is processed with HTML5 writer. This feature needs docutils 0.13 or newer. Default is ``False``. + + .. versionadded:: 1.6 .. _applehelp-options: @@ -1334,7 +1295,7 @@ the `Dublin Core metadata <http://dublincore.org/>`_. .. confval:: epub_description - The description of the document. The default value is ``''``. + The description of the document. The default value is ``'unknown'``. .. versionadded:: 1.4 @@ -1540,20 +1501,6 @@ the `Dublin Core metadata <http://dublincore.org/>`_. .. [#] https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode -.. confval:: epub3_page_progression_direction - - The global direction in which the content flows. - Allowed values are ``'ltr'`` (left-to-right), ``'rtl'`` (right-to-left) and - ``'default'``. The default value is ``'ltr'``. - - When the ``'default'`` value is specified, the Author is expressing no - preference and the Reading System may chose the rendering direction. - - .. versionadded:: 1.4 - - .. deprecated:: 1.5 - Use ``epub_writing_mode`` instead. - .. _latex-options: Options for LaTeX output @@ -1625,16 +1572,6 @@ These options influence LaTeX output. See further :doc:`latex`. .. versionadded:: 1.4 -.. confval:: latex_use_parts - - If true, the topmost sectioning unit is parts, else it is chapters. Default: - ``False``. - - .. versionadded:: 0.3 - - .. deprecated:: 1.4 - Use :confval:`latex_toplevel_sectioning`. - .. confval:: latex_appendices A list of document names to append as an appendix to all manuals. @@ -1650,13 +1587,6 @@ These options influence LaTeX output. See further :doc:`latex`. .. versionadded:: 1.0 -.. confval:: latex_use_modindex - - If true, add a module index to LaTeX documents. Default is ``True``. - - .. deprecated:: 1.0 - Use :confval:`latex_domain_indices`. - .. confval:: latex_show_pagerefs If true, add page references after internal references. This is very useful @@ -1681,18 +1611,39 @@ These options influence LaTeX output. See further :doc:`latex`. .. confval:: latex_keep_old_macro_names - If ``True`` (default) the ``\strong``, ``\code``, ``\bfcode``, ``\email``, + If ``True`` the ``\strong``, ``\code``, ``\bfcode``, ``\email``, ``\tablecontinued``, ``\titleref``, ``\menuselection``, ``\accelerator``, ``\crossref``, ``\termref``, and ``\optional`` text styling macros are pre-defined by Sphinx and may be user-customized by some ``\renewcommand``'s inserted either via ``'preamble'`` key or :dudir:`raw <raw-data-pass-through>` directive. If ``False``, only ``\sphinxstrong``, - etc... macros are defined (and may be redefined by user). Setting to - ``False`` may help solve macro name conflicts caused by user-added latex - packages. + etc... macros are defined (and may be redefined by user). - .. versionadded:: 1.4.5 + The default is ``False`` as it prevents macro name conflicts caused by + latex packages. For example (``lualatex`` or ``xelatex``) ``fontspec v2.6`` + has its own ``\strong`` macro. + .. versionadded:: 1.4.5 + .. versionchanged:: 1.6 + Default was changed from ``True`` to ``False``. + .. deprecated:: 1.6 + This setting will be removed at Sphinx 1.7. + +.. confval:: latex_use_latex_multicolumn + + If ``False`` (default), the LaTeX writer uses for merged cells in grid + tables Sphinx's own macros. They have the advantage to allow the same + contents as in non-merged cells (inclusive of literal blocks, lists, + blockquotes, ...). But they assume that the columns are separated by the + standard vertical rule. Further, in case the :rst:dir:`tabularcolumns` + directive was employed to inject more macros (using LaTeX's mark-up of the + type ``>{..}``, ``<{..}``, ``@{..}``) the multicolumn cannot ignore these + extra macros, contrarily to LaTeX's own ``\multicolumn``; but Sphinx's + version does arrange for ignoring ``\columncolor`` like the standard + ``\multicolumn`` does. Setting to ``True`` means to use LaTeX's standard + ``\multicolumn`` macro. + + .. versionadded:: 1.6 .. confval:: latex_elements @@ -1741,6 +1692,8 @@ These options influence LaTeX output. See further :doc:`latex`. .. versionchanged:: 1.5 For :confval:`latex_engine` set to ``'xelatex'``, the default is ``'\\usepackage{polyglossia}\n\\setmainlanguage{<language>}'``. + .. versionchanged:: 1.6 + ``'lualatex'`` uses same default setting as ``'xelatex'`` ``'fontpkg'`` Font package inclusion, default ``'\\usepackage{times}'`` (which uses Times and Helvetica). You can set this to ``''`` to use the Computer @@ -1751,6 +1704,8 @@ These options influence LaTeX output. See further :doc:`latex`. script. .. versionchanged:: 1.5 Defaults to ``''`` when :confval:`latex_engine` is ``'xelatex'``. + .. versionchanged:: 1.6 + Defaults to ``''`` also with ``'lualatex'``. ``'fncychap'`` Inclusion of the "fncychap" package (which makes fancy chapter titles), default ``'\\usepackage[Bjarne]{fncychap}'`` for English documentation @@ -1781,6 +1736,14 @@ These options influence LaTeX output. See further :doc:`latex`. * Keys that don't need to be overridden unless in special cases are: + ``'extraclassoptions'`` + The default is the empty string. Example: ``'extraclassoptions': + 'openany'`` will allow chapters (for documents of the ``'manual'`` + type) to start on any page. + + .. versionadded:: 1.2 + .. versionchanged:: 1.6 + Added this documentation. ``'maxlistdepth'`` LaTeX allows by default at most 6 levels for nesting list and quote-like environments, with at most 4 enumerated lists, and 4 bullet @@ -1816,6 +1779,8 @@ These options influence LaTeX output. See further :doc:`latex`. .. versionchanged:: 1.5 Defaults to ``'\\usepackage{fontspec}'`` when :confval:`latex_engine` is ``'xelatex'``. + .. versionchanged:: 1.6 + ``'lualatex'`` also uses ``fontspec`` per default. ``'geometry'`` "geometry" package inclusion, the default definition is: @@ -1935,27 +1900,6 @@ These options influence LaTeX output. See further :doc:`latex`. .. versionchanged:: 1.2 This overrides the files which is provided from Sphinx such as sphinx.sty. -.. confval:: latex_preamble - - Additional LaTeX markup for the preamble. - - .. deprecated:: 0.5 - Use the ``'preamble'`` key in the :confval:`latex_elements` value. - -.. confval:: latex_paper_size - - The output paper size (``'letter'`` or ``'a4'``). Default is ``'letter'``. - - .. deprecated:: 0.5 - Use the ``'papersize'`` key in the :confval:`latex_elements` value. - -.. confval:: latex_font_size - - The font size ('10pt', '11pt' or '12pt'). Default is ``'10pt'``. - - .. deprecated:: 0.5 - Use the ``'pointsize'`` key in the :confval:`latex_elements` value. - .. _text-options: diff --git a/doc/contents.rst b/doc/contents.rst index 92fb13fcb..36eed649e 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -17,6 +17,7 @@ Sphinx documentation contents config intl theming + setuptools templating latex markdown diff --git a/doc/develop.rst b/doc/develop.rst index f2f336cfa..2f14c945f 100644 --- a/doc/develop.rst +++ b/doc/develop.rst @@ -55,17 +55,17 @@ 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...). +- 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. - mockautodoc: mock imports. - mscgen: embed mscgen-formatted MSC (Message Sequence Chart)s. - napoleon: supports `Google style`_ and `NumPy style`_ docstrings. -- nicoviceo: embed videos from nicovideo +- nicovideo: embed videos from nicovideo - nwdiag: embed network diagrams by using nwdiag_ - omegat: support tools to collaborate with OmegaT_ (Sphinx 1.1 needed) -- osaka: convert standard Japanese doc to Osaka dialect (it is joke extension) +- osaka: convert standard Japanese doc to Osaka dialect (this is a joke extension) - paverutils: an alternate integration of Sphinx with Paver_. - phpdomain: an extension for PHP support - plantuml: embed UML diagram by using PlantUML_ @@ -113,7 +113,7 @@ own extensions. .. _Google Analytics: http://www.google.com/analytics/ .. _Google Chart: https://developers.google.com/chart/ .. _Google Maps: https://www.google.com/maps -.. _Google style: http://google-styleguide.googlecode.com/svn/trunk/pyguide.html +.. _Google style: https://google.github.io/styleguide/pyguide.html .. _NumPy style: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt .. _hyphenator: https://github.com/mnater/hyphenator .. _exceltable: http://pythonhosted.org/sphinxcontrib-exceltable/ diff --git a/doc/domains.rst b/doc/domains.rst index 3eaaf758d..1b0dfac8c 100644 --- a/doc/domains.rst +++ b/doc/domains.rst @@ -546,6 +546,10 @@ The C++ Domain The C++ domain (name **cpp**) supports documenting C++ projects. + +Directives +~~~~~~~~~~ + The following directives are available. All declarations can start with a visibility statement (``public``, ``private`` or ``protected``). @@ -741,6 +745,16 @@ a visibility statement (``public``, ``private`` or ``protected``). Holder of elements, to which it can provide access via :cpp:concept:`Iterator` s. +Options +....... + +Some directives support options: + +- ``:noindex:``, see :ref:`basic-domain-markup`. +- ``:tparam-line-spec:``, for templated declarations. + If specified, each template parameter will be rendered on a separate line. + + Constrained Templates ~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/ext/doctest.rst b/doc/ext/doctest.rst index 818b86007..d1cb3c31d 100644 --- a/doc/ext/doctest.rst +++ b/doc/ext/doctest.rst @@ -63,7 +63,7 @@ a comma-separated list of group names. default set of flags is specified by the :confval:`doctest_default_flags` configuration variable. - This directive supports two options: + This directive supports three options: * ``hide``, a flag option, hides the doctest block in other builders. By default it is shown as a highlighted doctest block. @@ -73,6 +73,19 @@ a comma-separated list of group names. explicit flags per example, with doctest comments, but they will show up in other builders too.) + * ``pyversion``, a string option, can be used to specify the required Python + version for the example to be tested. For instance, in the following case + the example will be tested only for Python versions greather than 3.3:: + + .. doctest:: + :pyversion: > 3.3 + + The supported operands are ``<``, ``<=``, ``==``, ``>=``, ``>``, and + comparison is performed by `distutils.version.LooseVersion + <https://www.python.org/dev/peps/pep-0386/#distutils>`__. + + .. versionadded:: 1.6 + Note that like with standard doctests, you have to use ``<BLANKLINE>`` to signal a blank line in the expected output. The ``<BLANKLINE>`` is removed when building presentation output (HTML, LaTeX etc.). diff --git a/doc/ext/example_google.py b/doc/ext/example_google.py index 34a720e36..5b4fa58df 100644 --- a/doc/ext/example_google.py +++ b/doc/ext/example_google.py @@ -83,7 +83,7 @@ def module_level_function(param1, param2=None, *args, **kwargs): of each parameter is required. The type and description of each parameter is optional, but should be included if not obvious. - If \*args or \*\*kwargs are accepted, + If ``*args`` or ``**kwargs`` are accepted, they should be listed as ``*args`` and ``**kwargs``. The format for a parameter is:: diff --git a/doc/ext/example_numpy.py b/doc/ext/example_numpy.py index 7a2db94cc..dbee080c3 100644 --- a/doc/ext/example_numpy.py +++ b/doc/ext/example_numpy.py @@ -106,7 +106,7 @@ def module_level_function(param1, param2=None, *args, **kwargs): The name of each parameter is required. The type and description of each parameter is optional, but should be included if not obvious. - If \*args or \*\*kwargs are accepted, + If ``*args`` or ``**kwargs`` are accepted, they should be listed as ``*args`` and ``**kwargs``. The format for a parameter is:: diff --git a/doc/ext/graphviz.rst b/doc/ext/graphviz.rst index 0994c932a..ef0483da7 100644 --- a/doc/ext/graphviz.rst +++ b/doc/ext/graphviz.rst @@ -77,20 +77,8 @@ It adds these directives: the graphviz code. .. versionadded:: 1.1 - All three directives support an ``inline`` flag that controls paragraph - breaks in the output. When set, the graph is inserted into the current - paragraph. If the flag is not given, paragraph breaks are introduced before - and after the image (the default). - -.. versionadded:: 1.1 All three directives support a ``caption`` option that can be used to give a - caption to the diagram. Naturally, diagrams marked as "inline" cannot have a - caption. - -.. deprecated:: 1.4 - ``inline`` option is deprecated. - All three directives generate inline node by default. If ``caption`` is given, - these generate block node instead. + caption to the diagram. .. versionchanged:: 1.4 All three directives support a ``graphviz_dot`` option that can be switch the @@ -100,6 +88,9 @@ It adds these directives: All three directives support a ``align`` option to align the graph horizontal. The values "left", "center", "right" are allowed. +.. versionadded:: 1.6 + All three directives support a ``name`` option to set the label to graph. + There are also these new config values: .. confval:: graphviz_dot diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst index b3ffb7af0..1df85907a 100644 --- a/doc/extdev/appapi.rst +++ b/doc/extdev/appapi.rst @@ -89,11 +89,6 @@ package. 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) @@ -293,6 +288,11 @@ package. Add the standard docutils :class:`Transform` subclass *transform* to the list of transforms that are applied after Sphinx parses a reST document. +.. method:: Sphinx.add_post_transform(transform) + + Add the standard docutils :class:`Transform` subclass *transform* to the list + of transforms that are applied before Sphinx writes a document. + .. method:: Sphinx.add_javascript(filename) Add *filename* to the list of JavaScript files that the default HTML template @@ -364,6 +364,12 @@ package. .. versionadded:: 1.4 +.. method:: Sphinx.add_env_collector(collector) + + Register an environment collector class (refs: :ref:`collector-api`) + + .. versionadded:: 1.6 + .. method:: Sphinx.require_sphinx(version) Compare *version* (which must be a ``major.minor`` version string, @@ -420,6 +426,10 @@ The application object also provides support for emitting leveled messages. the build; just raise an exception (:exc:`sphinx.errors.SphinxError` or a custom subclass) to do that. +.. deprecated:: 1.6 + + Please use :ref:`logging-api` instead. + .. automethod:: Sphinx.warn .. automethod:: Sphinx.info diff --git a/doc/extdev/collectorapi.rst b/doc/extdev/collectorapi.rst new file mode 100644 index 000000000..cb4c30bf3 --- /dev/null +++ b/doc/extdev/collectorapi.rst @@ -0,0 +1,9 @@ +.. _collector-api: + +Environment Collector API +------------------------- + +.. module:: sphinx.environment.collectors + +.. autoclass:: EnvironmentCollector + :members: diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst index b27db4b2d..85172abb6 100644 --- a/doc/extdev/index.rst +++ b/doc/extdev/index.rst @@ -50,7 +50,9 @@ APIs used for writing extensions appapi envapi builderapi + collectorapi markupapi domainapi parserapi nodes + logging diff --git a/doc/extdev/logging.rst b/doc/extdev/logging.rst new file mode 100644 index 000000000..50110c2a4 --- /dev/null +++ b/doc/extdev/logging.rst @@ -0,0 +1,77 @@ +.. _logging-api: + +Logging API +=========== + +.. function:: sphinx.util.logging.getLogger(name) + + Returns a logger wrapped by :class:`SphinxLoggerAdapter` with the specified *name*. + + Example usage:: + + from sphinx.util import logging # Load on top of python's logging module + + logger = logging.getLogger(__name__) + logger.info('Hello, this is an extension!') + +.. class:: SphinxLoggerAdapter(logging.LoggerAdapter) + + .. method:: SphinxLoggerAdapter.error(level, msg, *args, **kwargs) + .. method:: SphinxLoggerAdapter.critical(level, msg, *args, **kwargs) + .. method:: SphinxLoggerAdapter.warning(level, msg, *args, **kwargs) + + Logs a message on this logger with the specified level. + Basically, the arguments are as with python's logging module. + + In addition, Sphinx logger supports following keyword arguments: + + **type**, ***subtype*** + Categories of warning logs. It is used to suppress + warnings by :confval:`suppress_warnings` setting. + + **location** + Where the warning happened. It is used to include + the path and line number in each log. It allows docname, + tuple of docname and line number and nodes:: + + logger = sphinx.util.logging.getLogger(__name__) + logger.warning('Warning happened!', location='index') + logger.warning('Warning happened!', location=('chapter1/index', 10)) + logger.warning('Warning happened!', location=some_node) + + **color** + The color of logs. By default, warning level logs are + colored as ``"darkred"``. The others are not colored. + + .. method:: SphinxLoggerAdapter.log(level, msg, *args, **kwargs) + .. method:: SphinxLoggerAdapter.info(level, msg, *args, **kwargs) + .. method:: SphinxLoggerAdapter.verbose(level, msg, *args, **kwargs) + .. method:: SphinxLoggerAdapter.debug(level, msg, *args, **kwargs) + + Logs a message to this logger with the specified level. + Basically, the arguments are as with python's logging module. + + In addition, Sphinx logger supports following keyword arguments: + + **nonl** + If true, the logger does not fold lines at the end of the log message. + The default is ``False``. + + **color** + The color of logs. By default, debug level logs are + colored as ``"darkgray"``, and debug2 level ones are ``"lightgray"``. + The others are not colored. + +.. function:: pending_logging() + + Marks all logs as pending:: + + with pending_logging(): + logger.warning('Warning message!') # not flushed yet + some_long_process() + + # the warning is flushed here + +.. function:: pending_warnings() + + Marks warning logs as pending. Similar to :func:`pending_logging`. diff --git a/doc/extdev/nodes.rst b/doc/extdev/nodes.rst index 359410e25..5d8272eae 100644 --- a/doc/extdev/nodes.rst +++ b/doc/extdev/nodes.rst @@ -55,4 +55,3 @@ You should not need to generate the nodes below in extensions. .. autoclass:: start_of_file .. autoclass:: productionlist .. autoclass:: production -.. autoclass:: termsep diff --git a/doc/extdev/tutorial.rst b/doc/extdev/tutorial.rst index 10a14fab7..33b45035e 100644 --- a/doc/extdev/tutorial.rst +++ b/doc/extdev/tutorial.rst @@ -98,8 +98,9 @@ in which a Sphinx project is built: this works in several phases. Now that the metadata and cross-reference data of all existing documents is known, all temporary nodes are replaced by nodes that can be converted into - output. For example, links are created for object references that exist, and - simple literal nodes are created for those that don't. + output using components called tranform. For example, links are created for + object references that exist, and simple literal nodes are created for those + that don't. **Phase 4: Writing** @@ -246,7 +247,6 @@ todolist directive has neither content nor arguments that need to be handled. The ``todo`` directive function looks like this:: - from sphinx.util.compat import make_admonition from sphinx.locale import _ class TodoDirective(Directive): @@ -260,20 +260,20 @@ The ``todo`` directive function looks like this:: targetid = "todo-%d" % env.new_serialno('todo') targetnode = nodes.target('', '', ids=[targetid]) - ad = make_admonition(todo, self.name, [_('Todo')], self.options, - self.content, self.lineno, self.content_offset, - self.block_text, self.state, self.state_machine) + todo_node = todo('\n'.join(self.content)) + todo_node += nodes.title(_('Todo'), _('Todo')) + self.state.nested_parse(self.content, self.content_offset, todo_node) if not hasattr(env, 'todo_all_todos'): env.todo_all_todos = [] env.todo_all_todos.append({ 'docname': env.docname, 'lineno': self.lineno, - 'todo': ad[0].deepcopy(), + 'todo': todo_node.deepcopy(), 'target': targetnode, }) - return [targetnode] + ad + return [targetnode, todo_node] Several important things are covered here. First, as you can see, you can refer to the build environment instance using ``self.state.document.settings.env``. @@ -285,11 +285,10 @@ returns a new unique integer on each call and therefore leads to unique target names. The target node is instantiated without any text (the first two arguments). -An admonition is created using a standard docutils function (wrapped in Sphinx -for docutils cross-version compatibility). The first argument gives the node -class, in our case ``todo``. The third argument gives the admonition title (use -``arguments`` here to let the user specify the title). A list of nodes is -returned from ``make_admonition``. +On creating admonition node, the content body of the directive are parsed using +``self.state.nested_parse``. The first argument gives the content body, and +the second one gives content offset. The third argument gives the parent node +of parsed result, in our case the ``todo`` node. Then, the todo node is added to the environment. This is needed to be able to create a list of all todo entries throughout the documentation, in the place diff --git a/doc/faq.rst b/doc/faq.rst index eaa663d92..5924f5f68 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -201,7 +201,7 @@ The following list gives some hints for the creation of epub files: Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title) Error(prcgen):E24001: The table of content could not be built. -.. _Epubcheck: https://code.google.com/archive/p/epubcheck +.. _Epubcheck: https://github.com/IDPF/epubcheck .. _Calibre: http://calibre-ebook.com/ .. _FBreader: https://fbreader.org/ .. _Bookworm: http://www.oreilly.com/bookworm/index.html diff --git a/doc/intl.rst b/doc/intl.rst index 97f0e013e..dacced65b 100644 --- a/doc/intl.rst +++ b/doc/intl.rst @@ -74,7 +74,7 @@ Quick guide ^^^^^^^^^^^ `sphinx-intl`_ is a useful tool to work with Sphinx translation flow. -This section describe a easy way to translate with sphinx-intl. +This section describe an easy way to translate with sphinx-intl. #. Install `sphinx-intl`_ by :command:`pip install sphinx-intl` or :command:`easy_install sphinx-intl`. diff --git a/doc/invocation.rst b/doc/invocation.rst index 639b6880d..6cb16e919 100644 --- a/doc/invocation.rst +++ b/doc/invocation.rst @@ -404,7 +404,7 @@ variables to customize behavior: .. describe:: PAPER - The value for :confval:`latex_paper_size`. + The value for '"papersize"` key of :confval:`latex_elements`. .. describe:: SPHINXBUILD diff --git a/doc/latex.rst b/doc/latex.rst index ebc14765e..e2c518058 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -179,12 +179,8 @@ Here are the currently available options together with their default values. This is due to the way the LaTeX class ``jsbook`` handles the pointsize. - Or, one uses regular units but with ``nomag`` as document class option. - This can be achieved for example via:: - - 'pointsize': 'nomag,12pt', - - in the :confval:`latex_elements` configuration variable. + Or, one uses regular units but with ``nomag`` as extra document class + option (cf. ``'extraclassoptions'`` key of :confval:`latex_elements`.) .. versionadded:: 1.5.3 @@ -418,16 +414,20 @@ Let us now list some macros from the package file - text styling commands (they have one argument): ``\sphinx<foo>`` with ``<foo>`` being one of ``strong``, ``bfcode``, ``email``, ``tablecontinued``, ``titleref``, ``menuselection``, ``accelerator``, ``crossref``, ``termref``, - ``optional``. By default and for backwards compatibility the ``\sphinx<foo>`` - expands to ``\<foo>`` hence the user can choose to customize rather the latter - (the non-prefixed macros will be left undefined if option - :confval:`latex_keep_old_macro_names` is set to ``False`` in :file:`conf.py`.) - - .. versionchanged:: 1.4.5 - use of ``\sphinx`` prefixed macro names to limit possibilities of conflict - with user added packages: if - :confval:`latex_keep_old_macro_names` is set to ``False`` in - :file:`conf.py` only the prefixed names are defined. + ``optional``. The non-prefixed macros will still be defined if option + :confval:`latex_keep_old_macro_names` has been set to ``True`` (default is + ``False``), in which case the prefixed macros expand to the + non-prefixed ones. + + .. versionadded:: 1.4.5 + Use of ``\sphinx`` prefixed macro names to limit possibilities of conflict + with LaTeX packages. + .. versionchanged:: 1.6 + The default value of :confval:`latex_keep_old_macro_names` changes to + ``False``, and even if set to ``True``, if a non-prefixed macro + already exists at ``sphinx.sty`` loading time, only the ``\sphinx`` + prefixed one will be defined. The setting will be removed at 1.7. + - more text styling commands: ``\sphinxstyle<bar>`` with ``<bar>`` one of ``indexentry``, ``indexextra``, ``indexpageref``, ``topictitle``, ``sidebartitle``, ``othertitle``, ``sidebarsubtitle``, ``thead``, diff --git a/doc/markup/code.rst b/doc/markup/code.rst index c7cb0f911..cb3e55bdc 100644 --- a/doc/markup/code.rst +++ b/doc/markup/code.rst @@ -184,9 +184,17 @@ Includes string option, only lines that precede the first lines containing that string are included. + With lines selected using ``start-after`` it is still possible to use + ``lines``, the first allowed line having by convention the line number ``1``. + + When lines have been selected in any of the ways described above, the + line numbers in ``emphasize-lines`` also refer to the selection, with the + first selected line having number ``1``. + 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. + display the original line numbers. This can be done using the + ``lineno-match`` option, which is however allowed only when the selection + consists of contiguous lines. 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 @@ -212,7 +220,9 @@ Includes .. versionadded:: 1.3 The ``diff`` option. The ``lineno-match`` option. - + .. versionchanged:: 1.6 + With both ``start-after`` and ``lines`` in use, the first line as per + ``start-after`` is considered to be with line number ``1`` for ``lines``. Caption and name ^^^^^^^^^^^^^^^^ @@ -232,7 +242,7 @@ For example:: :rst:dir:`literalinclude` also supports the ``caption`` and ``name`` option. -``caption`` has a additional feature that if you leave the value empty, the shown +``caption`` has an additional feature that if you leave the value empty, the shown filename will be exactly the one given as an argument. diff --git a/doc/markup/misc.rst b/doc/markup/misc.rst index 0e1d104d6..c4b64e39c 100644 --- a/doc/markup/misc.rst +++ b/doc/markup/misc.rst @@ -201,6 +201,11 @@ Including content based on tags .. versionchanged:: 1.2 Added the name of the builder and the prefixes. + .. warning:: + + This directive is designed to control only content of document. It could + not control sections, labels and so on. + Tables ------ @@ -237,32 +242,76 @@ following directive exists: in proportion to the observed shares in a first pass where the table cells are rendered at their natural "horizontal" widths. - By default, Sphinx uses a table layout with ``L`` for every column. - - .. hint:: - - For columns which are known to be much narrower than the others it is - recommended to use the lowercase specifiers. For more information, check - the ``tabulary`` manual. + By default, Sphinx uses a table layout with ``J`` for every column. .. versionadded:: 0.3 -.. warning:: - - Tables with more than 30 rows are rendered using ``longtable``, not - ``tabulary``, in order to allow pagebreaks. + .. versionchanged:: 1.6 + Merged cells may now contain multiple paragraphs and are much better + handled, thanks to custom Sphinx LaTeX macros. This novel situation + motivated the switch to ``J`` specifier and not ``L`` by default. - Tables that contain list-like elements such as object descriptions, - blockquotes or any kind of lists cannot be set out of the box with - ``tabulary``. They are therefore set with the standard LaTeX ``tabular`` - environment if you don't give a ``tabularcolumns`` directive. If you do, the - table will be set with ``tabulary``, but you must use the ``p{width}`` - construct for the columns that contain these elements. + .. hint:: - Literal blocks do not work with ``tabulary`` at all, so tables containing a - literal block are always set with ``tabular``. Also, the verbatim - environment used for literal blocks only works in ``p{width}`` columns, which - means that by default, Sphinx generates such column specs for such tables. + Sphinx actually uses ``T`` specifier having done ``\newcolumntype{T}{J}``. + To revert to previous default, insert ``\newcolumntype{T}{L}`` in the + LaTeX preamble (see :confval:`latex_elements`). + + A frequent issue with tabulary is that columns with little contents are + "squeezed". The minimal column width is a tabulary parameter called + ``\tymin``. You may set it globally in the LaTeX preamble via + ``\setlength{\tymin}{40pt}`` for example. + + Else, use the :rst:dir:`tabularcolumns` directive with an explicit + ``p{40pt}`` (for example) for that column. You may use also ``l`` + specifier but this makes the task of setting column widths more difficult + if some merged cell intersects that column. + + .. warning:: + + Tables with more than 30 rows are rendered using ``longtable``, not + ``tabulary``, in order to allow pagebreaks. The ``L``, ``R``, ... specifiers + do not work for these tables. + + Tables that contain list-like elements such as object descriptions, + blockquotes or any kind of lists cannot be set out of the box with + ``tabulary``. They are therefore set with the standard LaTeX ``tabular`` (or + ``longtable``) environment if you don't give a ``tabularcolumns`` directive. + If you do, the table will be set with ``tabulary`` but you must use the + ``p{width}`` construct (or Sphinx's ``\X`` and ``\Y`` specifiers described + below) for the columns containing these elements. + + Literal blocks do not work with ``tabulary`` at all, so tables containing + a literal block are always set with ``tabular``. The verbatim environment + used for literal blocks only works in ``p{width}`` (and ``\X`` or ``\Y``) + columns, hence Sphinx generates such column specs for tables containing + literal blocks. + + Since Sphinx 1.5, the ``\X{a}{b}`` specifier is used (there *is* a backslash + in the specifier letter). It is like ``p{width}`` with the width set to a + fraction ``a/b`` of the current line width. You can use it in the + :rst:dir:`tabularcolumns` (it is not a problem if some LaTeX macro is also + called ``\X``.) + + It is *not* needed for ``b`` to be the total number of columns, nor for the + sum of the fractions of the ``\X`` specifiers to add up to one. For example + ``|\X{2}{5}|\X{1}{5}|\X{1}{5}|`` is legitimate and the table will occupy + 80% of the line width, the first of its three columns having the same width + as the sum of the next two. + + This is used by the ``:widths:`` option of the :dudir:`table` directive. + + Since Sphinx 1.6, there is also the ``\Y{f}`` specifier which admits a + decimal argument, such has ``\Y{0.15}``: this would have the same effect as + ``\X{3}{20}``. + + .. versionchanged:: 1.6 + + Merged cells from complex grid tables (either multi-row, multi-column, or + both) now allow blockquotes, lists, literal blocks, ... as do regular cells. + + Sphinx's merged cells interact well with ``p{width}``, ``\X{a}{b}``, ``Y{f}`` + and tabulary's columns. .. rubric:: Footnotes diff --git a/doc/markup/toctree.rst b/doc/markup/toctree.rst index a0161ee3c..78a72c1b4 100644 --- a/doc/markup/toctree.rst +++ b/doc/markup/toctree.rst @@ -41,7 +41,7 @@ tables of contents. The ``toctree`` directive is the central element. * Tables of contents from all those documents are inserted, with a maximum depth of two, that means one nested heading. ``toctree`` directives in those documents are also taken into account. - * Sphinx knows that the relative order of the documents ``intro``, + * Sphinx knows the relative order of the documents ``intro``, ``strings`` and so forth, and it knows that they are children of the shown document, the library index. From this information it generates "next chapter", "previous chapter" and "parent chapter" links. diff --git a/doc/setuptools.rst b/doc/setuptools.rst new file mode 100644 index 000000000..a8666a0bd --- /dev/null +++ b/doc/setuptools.rst @@ -0,0 +1,178 @@ +.. _setuptools: + +Setuptools integration +====================== + +Sphinx supports integration with setuptools and distutils through a custom +command - :class:`~sphinx.setup_command.BuildDoc`. + +Using setuptools integration +---------------------------- + +The Sphinx build can then be triggered from distutils, and some Sphinx +options can be set in ``setup.py`` or ``setup.cfg`` instead of Sphinx own +configuration file. + +For instance, from ``setup.py``:: + + # this is only necessary when not using setuptools/distribute + from sphinx.setup_command import BuildDoc + cmdclass = {'build_sphinx': BuildDoc} + + name = 'My project' + version = '1.2' + release = '1.2.0' + setup( + name=name, + author='Bernard Montgomery', + version=release, + cmdclass=cmdclass, + # these are optional and override conf.py settings + command_options={ + 'build_sphinx': { + 'project': ('setup.py', name), + 'version': ('setup.py', version), + 'release': ('setup.py', release)}}, + ) + +Or add this section in ``setup.cfg``:: + + [build_sphinx] + project = 'My project' + version = 1.2 + release = 1.2.0 + +Once configured, call this by calling the relevant command on ``setup.py``:: + + $ python setup.py build_sphinx + +Options for setuptools integration +---------------------------------- + +.. confval:: fresh-env + + A boolean that determines whether the saved environment should be discarded + on build. Default is false. + + This can also be set by passing the `-E` flag to ``setup.py``. + + .. code-block:: bash + + $ python setup.py build_sphinx -E + +.. confval:: all-files + + A boolean that determines whether all files should be built from scratch. + Default is false. + + This can also be set by passing the `-a` flag to ``setup.py``: + + .. code-block:: bash + + $ python setup.py build_sphinx -a + +.. confval:: source-dir + + The target source directory. This can be relative to the ``setup.py`` or + ``setup.cfg`` file, or it can be absolute. Default is ``''``. + + This can also be set by passing the `-s` flag to ``setup.py``: + + .. code-block:: bash + + $ python setup.py build_sphinx -s $SOURCE_DIR + +.. confval:: build-dir + + The target build directory. This can be relative to the ``setup.py`` or + ``setup.cfg`` file, or it can be absolute. Default is ``''``. + +.. confval:: config-dir + + Location of the configuration directory. This can be relative to the + ``setup.py`` or ``setup.cfg`` file, or it can be absolute. Default is + ``''``. + + This can also be set by passing the `-c` flag to ``setup.py``: + + .. code-block:: bash + + $ python setup.py build_sphinx -c $CONFIG_DIR + + .. versionadded:: 1.0 + +.. confval:: builder + + The builder or list of builders to use. Default is ``html``. + + This can also be set by passing the `-b` flag to ``setup.py``: + + .. code-block:: bash + + $ python setup.py build_sphinx -b $BUILDER + + .. versionchanged:: 1.6 + This can now be a comma- or space-separated list of builders + +.. confval:: warning-is-error + + A boolean that ensures Sphinx warnings will result in a failed build. + Default is false. + + This can also be set by passing the `-W` flag to ``setup.py``: + + .. code-block:: bash + + $ python setup.py build_sphinx -W + + .. versionadded:: 1.5 + +.. confval:: project + + The documented project's name. Default is ``''``. + + .. versionadded:: 1.0 + +.. confval:: version + + The short X.Y version. Default is ``''``. + + .. versionadded:: 1.0 + +.. confval:: release + + The full version, including alpha/beta/rc tags. Default is ``''``. + + .. versionadded:: 1.0 + +.. confval:: today + + How to format the current date, used as the replacement for ``|today|``. + Default is ``''``. + + .. versionadded:: 1.0 + +.. confval:: link-index + + A boolean that ensures index.html will be linked to the master doc. Default + is false. + + This can also be set by passing the `-i` flag to ``setup.py``: + + .. code-block:: bash + + $ python setup.py build_sphinx -i + + .. versionadded:: 1.0 + +.. confval:: copyright + + The copyright string. Default is ``''``. + + .. versionadded:: 1.3 + +.. confval:: pdb + + A boolean to configure ``pdb`` on exception. Default is false. + + .. versionadded:: 1.5 diff --git a/doc/templating.rst b/doc/templating.rst index b9f9410de..41acea91b 100644 --- a/doc/templating.rst +++ b/doc/templating.rst @@ -291,31 +291,12 @@ in the future. The value of :confval:`master_doc`, for usage with :func:`pathto`. -.. data:: next - - The next document for the navigation. This variable is either false or has - two attributes `link` and `title`. The title contains HTML markup. For - example, to generate a link to the next page, you can use this snippet:: - - {% if next %} - <a href="{{ next.link|e }}">{{ next.title }}</a> - {% endif %} - .. data:: pagename The "page name" of the current file, i.e. either the document name if the file is generated from a reST source, or the equivalent hierarchical name relative to the output directory (``[directory/]filename_without_extension``). -.. data:: parents - - A list of parent documents for navigation, structured like the :data:`next` - item. - -.. data:: prev - - Like :data:`next`, but for the previous page. - .. data:: project The value of :confval:`project`. @@ -369,16 +350,58 @@ In documents that are created from source files (as opposed to automatically-generated files like the module index, or documents that already are in HTML form), these variables are also available: +.. data:: body + + A string containing the content of the page in HTML form as produced by the HTML builder, + before the theme is applied. + +.. data:: display_toc + + A boolean that is True if the toc contains more than one entry. + .. data:: meta Document metadata (a dictionary), see :ref:`metadata`. +.. data:: metatags + + A string containing the page's HTML :dudir:`meta` tags. + +.. data:: next + + The next document for the navigation. This variable is either false or has + two attributes `link` and `title`. The title contains HTML markup. For + example, to generate a link to the next page, you can use this snippet:: + + {% if next %} + <a href="{{ next.link|e }}">{{ next.title }}</a> + {% endif %} + + +.. data:: page_source_suffix + + The suffix of the file that was rendered. Since we support a list of :confval:`source_suffix`, + this will allow you to properly link to the original source file. + +.. data:: parents + + A list of parent documents for navigation, structured like the :data:`next` + item. + +.. data:: prev + + Like :data:`next`, but for the previous page. + .. 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``. This has empty value on creating automatically-generated files. +.. data:: title + + The page title. + .. data:: toc The local table of contents for the current page, rendered as HTML bullet @@ -401,7 +424,4 @@ are in HTML form), these variables are also available: * ``includehidden`` (``False`` by default): if true, the TOC tree will also contain hidden entries. -.. data:: page_source_suffix - The suffix of the file that was rendered. Since we support a list of :confval:`source_suffix`, - this will allow you to properly link to the original source file. diff --git a/doc/tutorial.rst b/doc/tutorial.rst index bced21ade..ffabbd93e 100644 --- a/doc/tutorial.rst +++ b/doc/tutorial.rst @@ -308,6 +308,7 @@ More topics to be covered * ... - Static files - :doc:`Selecting a theme <theming>` +- :doc:`setuptools` - :ref:`Templating <templating>` - Using extensions - :ref:`Writing extensions <dev-extensions>` |