more_autodoc.regex

Specialized Documenter for regular expression variables, similar to autodata.

New in version 1.2.0.

Enable sphinx_toolbox.more_autodoc.regex by adding the following to the extensions variable in your conf.py:

extensions = [
    ...
    'sphinx_toolbox.more_autodoc.regex',
    ]

For more information see https://www.sphinx-doc.org/en/master/usage/extensions#third-party-extensions .

Usage

.. autoregex::

Directive to automatically document a regular expression variable.

The output is based on the autodata directive, and takes all of its options except :annotation:.

:no-value:

Don’t show the value of the variable.

:value: value (string)

Show this instead of the value taken from the Python source code.

:no-type:

Don’t show the type of the variable.

:no-flags:

Don’t show the flags of the Pattern object.

:flags: flags (string)

Show this instead of the flags taken from the Pattern object. This should be correctly formatted for insertion into reStructuredText, such as :py:data:`re.ASCII`.

Changed in version 2.7.0: The flags re.DEBUG and re.VERBOSE are now hidden as they don’t affect the regex itself.

:regex:

Formats a regular expression with coloured output.

:regex:`^Hello\s+[Ww]orld[.,](Lovely|Horrible) weather, isn't it (.*)?`

^Hello\s+[Ww]orld[.,](Lovely|Horrible) weather, isn't it (.*)?

Changed in version 2.11.0: Now generates coloured output with the LaTeX builder.

API Reference

Classes:

RegexDocumenter(directive, name[, indent])

Specialized Documenter subclass for regex patterns.

RegexParser()

Parser for regular expressions that outputs coloured output.

TerminalRegexParser()

RegexParser that outputs ANSI coloured output for the terminal.

HTMLRegexParser()

RegexParser that outputs styled HTML.

LaTeXRegexParser()

RegexParser that outputs styled LaTeX.

Functions:

parse_regex_flags(flags)

Convert regex flags into “bitwise-or’d” Sphinx xrefs.

no_formatting(value)

No-op that returns the value as a string.

span(css_class)

Returns a function that wraps a value in a span tag with the given class.

latex_textcolor(colour_name)

Returns a function that wraps a value in a LaTeX textcolor command for the given colour.

copy_asset_files(app[, exception])

Copy additional stylesheets into the HTML build directory.

setup(app)

Setup sphinx_toolbox.more_autodoc.regex.
class RegexDocumenter(directive, name, indent='')[source]

Bases: VariableDocumenter

Specialized Documenter subclass for regex patterns.

Methods:

add_content(more_content[, no_docstring])

Add content from docstrings, attribute documentation and the user.

add_directive_header(sig)

Add the directive’s header.

can_document_member(member, membername, …)

Called to see if a member can be documented by this documenter.
add_content(more_content, no_docstring=False)[source]

Add content from docstrings, attribute documentation and the user.

Parameters
add_directive_header(sig)[source]

Add the directive’s header.

Parameters

sig (str)

classmethod can_document_member(member, membername, isattr, parent)[source]

Called to see if a member can be documented by this documenter.

Parameters

  • member (Any) – The member being checked.

  • membername (str) – The name of the member.

  • isattr (bool)

  • parent (Any) – The parent of the member.

Return type

bool

class RegexParser[source]

Bases: object

Parser for regular expressions that outputs coloured output.

The formatting is controlled by the following variables:

  • AT_COLOUR – Used for e.g. ^\A\b\B\Z$

  • SUBPATTERN_COLOUR – Used for the parentheses around subpatterns, e.g. (Hello) World

  • IN_COLOUR – Used for the square brackets around character sets, e.g. [Hh]ello

  • REPEAT_COLOUR – Used for repeats, e.g. A?B+C*D{2,4}E{5}

  • REPEAT_BRACE_COLOUR – Used for the braces around numerical repeats.

  • CATEGORY_COLOUR – Used for categories, e.g. \d\D\s\D\w\W

  • BRANCH_COLOUR – Used for branches, e.g. (Lovely|Horrible) Weather

  • LITERAL_COLOUR – Used for literal characters.

  • ANY_COLOUR – Used for the “any” dot.

These are all Callable[[Any], str].

By default no formatting is performed.

Methods:

parse_pattern(regex)

Parse the given regular expression and return the formatted pattern.
parse_pattern(regex)[source]

Parse the given regular expression and return the formatted pattern.

Parameters

regex (Pattern)

Return type

str

class TerminalRegexParser[source]

Bases: RegexParser

RegexParser that outputs ANSI coloured output for the terminal.

The formatting is controlled by the following functions, which are instances of consolekit.terminal_colours.Colour:

  • AT_COLOUR -> YELLOW – Used for e.g. ^\A\b\B\Z$

  • SUBPATTERN_COLOUR -> LIGHTYELLOW_EX – Used for the parentheses around subpatterns, e.g. (Hello) World

  • IN_COLOUR -> LIGHTRED_EX – Used for the square brackets around character sets, e.g. [Hh]ello

  • REPEAT_COLOUR -> LIGHTBLUE_EX – Used for repeats, e.g. A?B+C*D{2,4}E{5}

  • REPEAT_BRACE_COLOUR -> YELLOW – Used for the braces around numerical repeats.

  • CATEGORY_COLOUR -> LIGHTYELLOW_EX – Used for categories, e.g. \d\D\s\D\w\W

  • BRANCH_COLOUR -> YELLOW – Used for branches, e.g. (Lovely|Horrible) Weather

  • LITERAL_COLOUR -> GREEN – Used for literal characters.

  • ANY_COLOUR -> YELLOW – Used for the “any” dot.

class HTMLRegexParser[source]

Bases: RegexParser

RegexParser that outputs styled HTML.

The formatting is controlled by the following functions, which wrap the character in a span tag with an appropriate CSS class:

  • AT_COLOUR -> regex_at – Used for e.g. ^\A\b\B\Z$

  • SUBPATTERN_COLOUR -> regex_subpattern – Used for the parentheses around subpatterns, e.g. (Hello) World

  • IN_COLOUR -> regex_in – Used for the square brackets around character sets, e.g. [Hh]ello

  • REPEAT_COLOUR -> regex_repeat – Used for repeats, e.g. A?B+C*D{2,4}E{5}

  • REPEAT_BRACE_COLOUR -> regex_repeat_brace – Used for the braces around numerical repeats.

  • CATEGORY_COLOUR -> regex_category – Used for categories, e.g. \d\D\s\D\w\W

  • BRANCH_COLOUR -> regex_branch – Used for branches, e.g. (Lovely|Horrible) Weather

  • LITERAL_COLOUR -> regex_literal – Used for literal characters.

  • ANY_COLOUR -> regex_any – Used for the “any” dot.

Additionally, all span tags the regex class, and the surrounding code tag has the following classes: docutils literal notranslate regex.

class LaTeXRegexParser[source]

Bases: RegexParser

RegexParser that outputs styled LaTeX.

The formatting is controlled by the following functions, which wrap the character in a LaTeX textcolor command for an appropriate colour:

  • AT_COLOUR -> regex_at – Used for e.g. ^\A\b\B\Z$

  • SUBPATTERN_COLOUR -> regex_subpattern – Used for the parentheses around subpatterns, e.g. (Hello) World

  • IN_COLOUR -> regex_in – Used for the square brackets around character sets, e.g. [Hh]ello

  • REPEAT_COLOUR -> regex_repeat – Used for repeats, e.g. A?B+C*D{2,4}E{5}

  • REPEAT_BRACE_COLOUR -> regex_repeat_brace – Used for the braces around numerical repeats.

  • CATEGORY_COLOUR -> regex_category – Used for categories, e.g. \d\D\s\D\w\W

  • BRANCH_COLOUR -> regex_branch – Used for branches, e.g. (Lovely|Horrible) Weather

  • LITERAL_COLOUR -> regex_literal – Used for literal characters.

  • ANY_COLOUR -> regex_any – Used for the “any” dot.

New in version 2.11.0.

parse_regex_flags(flags)[source]

Convert regex flags into “bitwise-or’d” Sphinx xrefs.

Parameters

flags (int)

Return type

str

no_formatting(value)[source]

No-op that returns the value as a string.

Used for unformatted output.

Return type

str

span(css_class)[source]

Returns a function that wraps a value in a span tag with the given class.

Parameters

css_class (str)

Return type

Callable[[Any], str]

latex_textcolor(colour_name)[source]

Returns a function that wraps a value in a LaTeX textcolor command for the given colour.

New in version 2.11.0.

Parameters

colour_name (str)

Return type

Callable[[Any], str]

copy_asset_files(app, exception=None)[source]

Copy additional stylesheets into the HTML build directory.

Parameters

  • app (Sphinx) – The Sphinx application.

  • exception (Optional[Exception]) – Any exception which occurred and caused Sphinx to abort. Default None.

setup(app)[source]

Setup sphinx_toolbox.more_autodoc.regex.

Parameters

app (Sphinx) – The Sphinx application.

Return type

SphinxExtMetadata