From da09100869e961f92f5bc7e3f36d83050ab4931a Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 21 Jan 2014 09:54:31 +0100 Subject: [PATCH 01/13] doc: add exceptions from sphinx.errors --- doc/extdev/appapi.rst | 50 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst index b91f6c72f..7769fbca0 100644 --- a/doc/extdev/appapi.rst +++ b/doc/extdev/appapi.rst @@ -356,6 +356,12 @@ Producing messages / logging The application object also provides support for emitting leveled messages. +.. note:: + + There is no "error" call: in Sphinx, errors are defined as things that stop + the build; for that just raise an exception (:exc:`sphinx.errors.SphinxError` + or a custom subclass) to do that. + .. automethod:: Sphinx.warn .. automethod:: Sphinx.info @@ -532,3 +538,47 @@ The template bridge .. autoclass:: TemplateBridge :members: + + +.. _exceptions: + +Exceptions +---------- + +.. module:: sphinx.errors + +.. class:: SphinxError + + This is the base class for "nice" exceptions. When such an exception is + raised, Sphinx will abort the build and present the exception category and + message to the user. + + Extensions are encouraged to derive from this exception for their custom + errors. + + Exceptions *not* derived from :exc:`SphinxError` are treated as unexpected + and shown to the user with a part of the traceback (and the full traceback + saved in a temporary file). + + .. attribute:: category + + Description of the exception "category", used in converting the exception + to a string ("category: message"). Should be set accordingly in + subclasses. + +.. class:: ConfigError + + Used for erroneous values or nonsensical combinations of configuration + values. + +.. class:: ExtensionError + + Used for errors in setting up extensions. + +.. class:: ThemeError + + Used for errors to do with themes. + +.. class:: VersionRequirementError + + Raised when the docs require a higher Sphinx version than the current one. From cc8d29dcabdf4adddd75d39751078fcc4c03fea2 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 21 Jan 2014 10:04:11 +0100 Subject: [PATCH 02/13] actually use exception markup --- doc/extdev/appapi.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst index 7769fbca0..938226083 100644 --- a/doc/extdev/appapi.rst +++ b/doc/extdev/appapi.rst @@ -547,7 +547,7 @@ Exceptions .. module:: sphinx.errors -.. class:: SphinxError +.. exception:: SphinxError This is the base class for "nice" exceptions. When such an exception is raised, Sphinx will abort the build and present the exception category and @@ -566,19 +566,19 @@ Exceptions to a string ("category: message"). Should be set accordingly in subclasses. -.. class:: ConfigError +.. exception:: ConfigError Used for erroneous values or nonsensical combinations of configuration values. -.. class:: ExtensionError +.. exception:: ExtensionError Used for errors in setting up extensions. -.. class:: ThemeError +.. exception:: ThemeError Used for errors to do with themes. -.. class:: VersionRequirementError +.. exception:: VersionRequirementError Raised when the docs require a higher Sphinx version than the current one. From 6b33e3fea48bff97a4ea1f6c88584b413964da14 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 21 Jan 2014 10:05:23 +0100 Subject: [PATCH 03/13] remove duplicate wording --- doc/extdev/appapi.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst index 938226083..24136f742 100644 --- a/doc/extdev/appapi.rst +++ b/doc/extdev/appapi.rst @@ -359,8 +359,8 @@ The application object also provides support for emitting leveled messages. .. note:: There is no "error" call: in Sphinx, errors are defined as things that stop - the build; for that just raise an exception (:exc:`sphinx.errors.SphinxError` - or a custom subclass) to do that. + the build; just raise an exception (:exc:`sphinx.errors.SphinxError` or a + custom subclass) to do that. .. automethod:: Sphinx.warn From fb5a1a09a01a2be1ae0adabb4836abc33f91edc8 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 21 Jan 2014 10:32:30 +0100 Subject: [PATCH 04/13] some directive creation docs --- doc/extdev/markupapi.rst | 130 ++++++++++++++++++++++++++++++++++++++- doc/extdev/tutorial.rst | 8 +-- 2 files changed, 133 insertions(+), 5 deletions(-) diff --git a/doc/extdev/markupapi.rst b/doc/extdev/markupapi.rst index 8f6c29b1f..3c09687eb 100644 --- a/doc/extdev/markupapi.rst +++ b/doc/extdev/markupapi.rst @@ -1,6 +1,9 @@ Docutils markup API =================== +This section describes the API for adding ReST markup elements (roles and +directives). + Roles ----- @@ -8,4 +11,129 @@ Roles Directives ---------- -TODO. +Directives are handled by classes derived from +``docutils.parsers.rst.Directive``. They have to be registered by an extension +using :meth:`.Sphinx.add_directive` or :meth:`.Sphinx.add_directive_to_domain`. + +.. module:: docutils.parsers.rst + +.. class:: Directive + + The markup syntax of the new directive is determined by the follow five class + attributes: + + .. autoattribute:: required_arguments + .. autoattribute:: optional_arguments + .. autoattribute:: final_argument_whitespace + .. autoattribute:: option_spec + + Option validator functions take a single parameter, the option argument + (or ``None`` if not given), and should validate it or convert it to the + proper form. They raise :exc:`ValueError` or :exc:`TypeError` to indicate + failure. + + There are several predefined and possibly useful validators in the + :mod:`docutils.parsers.rst.directives` module. + + .. autoattribute:: has_content + + New directives must implement the :meth:`run` method: + + .. method:: run() + + This method must process the directive arguments, options and content, and + return a list of Docutils/Sphinx nodes that will be inserted into the + document tree at the point where the directive was encountered. + + Instance attributes that are always set on the directive are: + + .. attribute:: name + + The directive name (useful when registering the same directive class under + multiple names). + + .. attribute:: arguments + + The arguments given to the directive, as a list. + + .. attribute:: options + + The options given to the directive, as a dictionary mapping option names + to validated/converted values. + + .. attribute:: content + + The directive content, if given, as a :class:`.ViewList`. + + .. attribute:: lineno + + The absolute line number on which the directive appeared. This is not + always a useful value; use :attr:`srcline` instead. + + .. attribute:: src + + The source file of the directive. + + .. attribute:: srcline + + The line number in the source file on which the directive appeared. + + .. attribute:: content_offset + + Internal offset of the directive content. Used when calling + ``nested_parse`` (see below). + + .. attribute:: block_text + + The string containing the entire directive. + + .. attribute:: state + state_machine + + The state and state machine which controls the parsing. Used for + ``nested_parse``. + + +ViewLists +^^^^^^^^^ + +Docutils represents document source lines in a class +``docutils.statemachine.ViewList``. This is a list with extended functionality +-- for one, slicing creates views of the original list, and also the list +contains information about the source line numbers. + +The :attr:`Directive.content` attribute is a ViewList. If you generate content +to be parsed as ReST, you have to create a ViewList yourself. Important for +content generation are the following points: + +* The constructor takes a list of strings (lines) and a source (document) name. + +* The ``.append()`` method takes a line and a source name as well. + + +Parsing directive content as ReST +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Many directives will contain more markup that must be parsed. To do this, use +one of the following APIs from the :meth:`Directive.run` method: + +* ``self.state.nested_parse`` +* :func:`sphinx.util.nodes.nested_parse_with_titles` -- this allows titles in + the parsed content. + +Both APIs parse the content into a given node. They are used like this:: + + node = docutils.nodes.paragraph() + # either + nested_parse_with_titles(self.state, self.result, node) + # or + self.state.nested_parse(self.result, 0, node) + +If you don't need the wrapping node, you can use any concrete node type and +return ``node.children`` from the Directive. + + +.. seealso:: + + `Creating directives `_ + HOWTO of the Docutils documentation diff --git a/doc/extdev/tutorial.rst b/doc/extdev/tutorial.rst index 382641904..a03d6e08b 100644 --- a/doc/extdev/tutorial.rst +++ b/doc/extdev/tutorial.rst @@ -225,10 +225,10 @@ The Directive Classes --------------------- A directive class is a class deriving usually from -``docutils.parsers.rst.Directive``. The directive interface is covered in -detail in the `docutils documentation`_; the important thing is that the class -has attributes that configure the allowed markup and a method ``run`` that -returns a list of nodes. +:class:`docutils.parsers.rst.Directive`. The directive interface is also +covered in detail in the `docutils documentation`_; the important thing is that +the class has attributes that configure the allowed markup and a method ``run`` +that returns a list of nodes. The ``todolist`` directive is quite simple:: From 15989db2a79e7273d7b794c375e68420739a903d Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 21 Jan 2014 10:33:40 +0100 Subject: [PATCH 05/13] markup fix --- sphinx/application.py | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/sphinx/application.py b/sphinx/application.py index 3807f542b..e598ced80 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -242,9 +242,11 @@ class Sphinx(object): *prefix* usually should not be changed. - .. note:: For warnings emitted during parsing, you should use - :meth:`.BuildEnvironment.warn` since that will collect all - warnings during parsing for later output. + .. note:: + + For warnings emitted during parsing, you should use + :meth:`.BuildEnvironment.warn` since that will collect all + warnings during parsing for later output. """ if isinstance(location, tuple): docname, lineno = location From f1a26f35348309a4e4e2a710281455e834169df0 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 21 Jan 2014 10:39:07 +0100 Subject: [PATCH 06/13] dont suggest reporting issues to user list anymore --- sphinx/cmdline.py | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/sphinx/cmdline.py b/sphinx/cmdline.py index 99001a283..e2c947c7e 100644 --- a/sphinx/cmdline.py +++ b/sphinx/cmdline.py @@ -291,8 +291,6 @@ def main(argv): 'error, so that a better error message ' 'can be provided next time.') print >>error, ( - 'Either send bugs to the mailing list at ' - ',\n' - 'or report them in the tracker at ' - '. Thanks!') + 'A bug report can be filed in the tracker at ' + '. Thanks!') return 1 From b182ce5ee30a7f5c72be1c5e8bc2549e931275c1 Mon Sep 17 00:00:00 2001 From: Dmitry Shachnev Date: Tue, 21 Jan 2014 20:55:06 +0400 Subject: [PATCH 07/13] setup_command.py: Add missing DistutilsOptionError import --- sphinx/setup_command.py | 1 + 1 file changed, 1 insertion(+) diff --git a/sphinx/setup_command.py b/sphinx/setup_command.py index 7999bf591..f7ca7a9d2 100644 --- a/sphinx/setup_command.py +++ b/sphinx/setup_command.py @@ -17,6 +17,7 @@ import os import types from StringIO import StringIO from distutils.cmd import Command +from distutils.errors import DistutilsOptionError from sphinx.application import Sphinx from sphinx.util.console import darkred, nocolor, color_terminal From 1219dce8c6b07db7ac03b7044227ab3691414fc3 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 21 Jan 2014 18:41:19 +0100 Subject: [PATCH 08/13] changelog for PR#213. --- CHANGES | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGES b/CHANGES index 6879a0c17..348dcd0de 100644 --- a/CHANGES +++ b/CHANGES @@ -6,8 +6,8 @@ Bugs fixed * PR#211: When checking for existence of the :confval:`html_logo` file, check the full relative path and not the basename. - * PR#212: Fix traceback with autodoc and ``__init__`` methods without docstring. +* PR#213: Fix a missing import in the setup command. Release 1.2.1 (released Jan 19, 2014) From a683b7147a188ec4ed66fb216b37f35f8f1d1f23 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 21 Jan 2014 19:09:38 +0100 Subject: [PATCH 09/13] extdev changelog entry --- CHANGES | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CHANGES b/CHANGES index 348dcd0de..495211071 100644 --- a/CHANGES +++ b/CHANGES @@ -9,6 +9,11 @@ Bugs fixed * PR#212: Fix traceback with autodoc and ``__init__`` methods without docstring. * PR#213: Fix a missing import in the setup command. +Documentation +------------- + +* Extended the :ref:`documentation about building extensions `. + Release 1.2.1 (released Jan 19, 2014) ===================================== From 652b766af975b830dfa7071b5504df0bb2d03435 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 22 Jan 2014 17:24:06 +0100 Subject: [PATCH 10/13] Closes #1355: compatibility fix for Django docs. --- sphinx/writers/html.py | 1 + 1 file changed, 1 insertion(+) diff --git a/sphinx/writers/html.py b/sphinx/writers/html.py index 2d68564f5..cc6da5833 100644 --- a/sphinx/writers/html.py +++ b/sphinx/writers/html.py @@ -79,6 +79,7 @@ class HTMLTranslator(BaseTranslator): self.permalink_text = self.encode(self.permalink_text) self.secnumber_suffix = builder.config.html_secnumber_suffix self.param_separator = '' + self.optional_param_level = 0 self._table_row_index = 0 def visit_start_of_file(self, node): From 38f47bc0ef8be5137eea33eb5386860a560d4c8c Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 22 Jan 2014 17:28:04 +0100 Subject: [PATCH 11/13] Closes #1356: link to page with valid Pygments lexer alias --- doc/markup/code.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/markup/code.rst b/doc/markup/code.rst index 98fdad7db..957774f05 100644 --- a/doc/markup/code.rst +++ b/doc/markup/code.rst @@ -60,7 +60,8 @@ installed) and handled in a smart way: certain well-recognizable languages) * ``rest`` * ``c`` - * ... and any other lexer name that Pygments supports. + * ... and any other `lexer alias that Pygments supports + `_. * If highlighting with the selected language fails (i.e. Pygments emits an "Error" token), the block is not highlighted in any way. From 2acaf03270ce0235397c3b9a81f51f22a0fa626b Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 22 Jan 2014 17:42:38 +0100 Subject: [PATCH 12/13] Closes #1357: Option names documented by :rst:dir:`option` are now again allowed to not start with a dash or slash, and referencing them will work correctly. --- CHANGES | 2 ++ doc/domains.rst | 14 +++++++++----- sphinx/domains/std.py | 38 +++++++++++++++++++++++--------------- 3 files changed, 34 insertions(+), 20 deletions(-) diff --git a/CHANGES b/CHANGES index 495211071..b970416af 100644 --- a/CHANGES +++ b/CHANGES @@ -8,6 +8,8 @@ Bugs fixed the full relative path and not the basename. * PR#212: Fix traceback with autodoc and ``__init__`` methods without docstring. * PR#213: Fix a missing import in the setup command. +* #1357: Option names documented by :rst:dir:`option` are now again allowed to + not start with a dash or slash, and referencing them will work correctly. Documentation ------------- diff --git a/doc/domains.rst b/doc/domains.rst index 024edc9a5..4b5a9032b 100644 --- a/doc/domains.rst +++ b/doc/domains.rst @@ -632,16 +632,20 @@ There is a set of directives allowing documenting command-line programs: .. rst:directive:: .. option:: name args, name args, ... - Describes a command line option or switch. Option argument names should be - enclosed in angle brackets. Example:: + Describes a command line argument or switch. Option argument names should be + enclosed in angle brackets. Examples:: + + .. option:: dest_dir + + Destination directory. .. option:: -m , --module Run a module as a script. - The directive will create a cross-reference target named after the *first* - option, referencable by :rst:role:`option` (in the example case, you'd use - something like ``:option:`-m```). + The directive will create cross-reference targets for the given options, + referencable by :rst:role:`option` (in the example case, you'd use something + like ``:option:`dest_dir```, ``:option:`-m```, or ``:option:`--module```). .. rst:directive:: .. envvar:: name diff --git a/sphinx/domains/std.py b/sphinx/domains/std.py index 895e35e56..50c7553e0 100644 --- a/sphinx/domains/std.py +++ b/sphinx/domains/std.py @@ -27,7 +27,7 @@ from sphinx.util.compat import Directive # RE for option descriptions -option_desc_re = re.compile(r'((?:/|-|--)[-_a-zA-Z0-9]+)(\s*.*)') +option_desc_re = re.compile(r'((?:/|-|--)?[-_a-zA-Z0-9]+)(\s*.*)') class GenericObject(ObjectDescription): @@ -143,7 +143,7 @@ class Cmdoption(ObjectDescription): self.env.warn( self.env.docname, 'Malformed option description %r, should ' - 'look like "-opt args", "--opt args" or ' + 'look like "opt", "-opt args", "--opt args" or ' '"/opt args"' % potential_option, self.lineno) continue optname, args = m.groups() @@ -153,25 +153,33 @@ class Cmdoption(ObjectDescription): signode += addnodes.desc_addname(args, args) if not count: firstname = optname + signode['allnames'] = [optname] + else: + signode['allnames'].append(optname) count += 1 if not firstname: raise ValueError return firstname - def add_target_and_index(self, name, sig, signode): - targetname = name.replace('/', '-') + def add_target_and_index(self, firstname, sig, signode): currprogram = self.env.temp_data.get('std:program') - if currprogram: - targetname = '-' + currprogram + targetname - targetname = 'cmdoption' + targetname - signode['ids'].append(targetname) - self.state.document.note_explicit_target(signode) - self.indexnode['entries'].append( - ('pair', _('%scommand line option; %s') % - ((currprogram and currprogram + ' ' or ''), sig), - targetname, '')) - self.env.domaindata['std']['progoptions'][currprogram, name] = \ - self.env.docname, targetname + for optname in signode.get('allnames', []): + targetname = optname.replace('/', '-') + if not targetname.startswith('-'): + targetname = '-arg-' + targetname + if currprogram: + targetname = '-' + currprogram + targetname + targetname = 'cmdoption' + targetname + signode['ids'].append(targetname) + self.state.document.note_explicit_target(signode) + self.env.domaindata['std']['progoptions'][currprogram, optname] = \ + self.env.docname, targetname + # create only one index entry for the whole option + if optname == firstname: + self.indexnode['entries'].append( + ('pair', _('%scommand line option; %s') % + ((currprogram and currprogram + ' ' or ''), sig), + targetname, '')) class Program(Directive): From 216c664187b19e0244f1a8f57a28bb9e91a49364 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 22 Jan 2014 18:04:44 +0100 Subject: [PATCH 13/13] remove mention of development egg. --- setup.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/setup.py b/setup.py index 553cf12d2..876c0782a 100644 --- a/setup.py +++ b/setup.py @@ -39,9 +39,6 @@ Among its features are the following: * Various extensions are available, e.g. for automatic testing of snippets and inclusion of appropriately formatted docstrings * Setuptools integration - -A development egg can be found `here -`_. ''' requires = ['Pygments>=1.2', 'docutils>=0.7']