Sphinx Extension (runthis.sphinxext)

Sphinx extension which adds a directive for RunThis code-block that may be executed by clicking the “RunThis” button above the code block.

The directive, like the standard code-block directive, takes a language argument and an optional linenos parameter.

Examples:

class runthis.sphinxext.RunThisCodeBlock(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

RunThis code block is executed as needed

add_name(node)

Append self.options[‘name’] to node[‘names’] if it exists.

Also normalize the name string and register it as explicit target.

assert_has_content()

Throw an ERROR-level DirectiveError if the directive doesn’t have contents.

property config

Reference to the Config object.

debug(message)
directive_error(level, message)

Return a DirectiveError suitable for being thrown as an exception.

Call “raise self.directive_error(level, message)” from within a directive implementation to return one single system message at level level, which automatically gets the directive block and the line number added.

Preferably use the debug, info, warning, error, or severe wrapper methods, e.g. self.error(message) to generate an ERROR-level directive error.

property env

Reference to the BuildEnvironment object.

error(message)
final_argument_whitespace = False
has_content = True
info(message)
option_spec = {'caption': <function unchanged_required>, 'class': <function class_option>, 'dedent': <class 'int'>, 'emphasize-lines': <function unchanged_required>, 'force': <function flag>, 'label': <class 'str'>, 'lineno-start': <class 'int'>, 'linenos': <function flag>, 'name': <function unchanged>, 'starthidden': <function nice_bool>}
optional_arguments = 1
required_arguments = 0
run()
set_source_info(node: docutils.nodes.Node) → None

Set source and line number to the node.

severe(message)
warning(message)
runthis.sphinxext.depart_runthis_html(self, node)

Depart hidden code block

runthis.sphinxext.nice_bool(arg)
class runthis.sphinxext.runthis_code_block(rawsource='', text='', *children, **attributes)
append(item)
append_attr_list(attr, values)

For each element in values, if it does not exist in self[attr], append it.

NOTE: Requires self[attr] and values to be sequence type and the former should specifically be a list.

asdom(dom=None)

Return a DOM fragment representation of this Node.

astext()

Return a string representation of this Node.

attlist()
basic_attributes = ('ids', 'classes', 'names', 'dupnames')
child_text_separator = ''
clear()
coerce_append_attr_list(attr, value)

First, convert both self[attr] and value to a non-string sequence type; if either is not already a sequence, convert it to a list of one element. Then call append_attr_list.

NOTE: self[attr] and value both must not be None.

copy() → docutils.nodes.Element
copy_attr_coerce(attr, value, replace)

If attr is an attribute of self and either self[attr] or value is a list, convert all non-sequence values to a sequence of 1 element and then concatenate the two sequence, setting the result to self[attr]. If both self[attr] and value are non-sequences and replace is True or self[attr] is None, replace self[attr] with value. Otherwise, do nothing.

copy_attr_concatenate(attr, value, replace)

If attr is an attribute of self and both self[attr] and value are lists, concatenate the two sequences, setting the result to self[attr]. If either self[attr] or value are non-sequences and replace is True or self[attr] is None, replace self[attr] with value. Otherwise, do nothing.

copy_attr_consistent(attr, value, replace)

If replace is True or self[attr] is None, replace self[attr] with value. Otherwise, do nothing.

copy_attr_convert(attr, value, replace=True)

If attr is an attribute of self, set self[attr] to [self[attr], value], otherwise set self[attr] to value.

NOTE: replace is not used by this function and is kept only for

compatibility with the other copy functions.

deepcopy()

Return a deep copy of self (also copying children).

delattr(attr)
document = None
emptytag()
endtag()
extend(item)
first_child_matching_class(childclass, start=0, end=9223372036854775807)

Return the index of the first child whose class exactly matches.

Parameters:

  • childclass: A Node subclass to search for, or a tuple of Node classes. If a tuple, any of the classes may match.

  • start: Initial index to check.

  • end: Initial index to not check.

first_child_not_matching_class(childclass, start=0, end=9223372036854775807)

Return the index of the first child whose class does not match.

Parameters:

  • childclass: A Node subclass to skip, or a tuple of Node classes. If a tuple, none of the classes may match.

  • start: Initial index to check.

  • end: Initial index to not check.

get(key, failobj=None)
get_language_code(fallback='')

Return node’s language tag.

Look iteratively in self and parents for a class argument starting with language- and return the remainder of it (which should be a BCP49 language tag) or the fallback.

has_key(attr)
hasattr(attr)
index(item)
insert(index, item)
is_not_default(key)
classmethod is_not_known_attribute(attr)

Returns True if and only if the given attribute is NOT recognized by this class.

classmethod is_not_list_attribute(attr)

Returns True if and only if the given attribute is NOT one of the basic list attributes defined for all Elements.

known_attributes = ('ids', 'classes', 'names', 'dupnames', 'backrefs', 'source', 'rawsource')
line = None
list_attributes = ('ids', 'classes', 'names', 'dupnames', 'backrefs')
local_attributes = ('backrefs',)
next_node(condition=None, include_self=False, descend=True, siblings=False, ascend=False)

Return the first node in the iterable returned by traverse(), or None if the iterable is empty.

Parameter list is the same as of traverse. Note that include_self defaults to False, though.

non_default_attributes()
note_referenced_by(name=None, id=None)

Note that this Element has been referenced by its name name or id id.

parent = None
pformat(indent=' ', level=0)

Return an indented pseudo-XML representation, for test purposes.

Override in subclasses.

pop(i=-1)
remove(item)
replace(old, new)

Replace one child Node with another child or children.

replace_attr(attr, value, force=True)

If self[attr] does not exist or force is True or omitted, set self[attr] to value, otherwise do nothing.

replace_self(new)

Replace self node with new, where new is a node or a list of nodes.

set_class(name)

Add a new class to the “classes” attribute.

setdefault(key, failobj=None)
setup_child(child)
shortrepr()
source = None
starttag(quoteattr=None)
tagname = None
traverse(condition=None, include_self=True, descend=True, siblings=False, ascend=False)

Return an iterable containing

  • self (if include_self is true)

  • all descendants in tree traversal order (if descend is true)

  • all siblings (if siblings is true) and their descendants (if also descend is true)

  • the siblings of the parent (if ascend is true) and their descendants (if also descend is true), and so on

If condition is not None, the iterable contains only nodes for which condition(node) is true. If condition is a node class cls, it is equivalent to a function consisting of return isinstance(node, cls).

If ascend is true, assume siblings to be true as well.

For example, given the following tree:

<paragraph>
    <emphasis>      <--- emphasis.traverse() and
        <strong>    <--- strong.traverse() are called.
            Foo
        Bar
    <reference name="Baz" refid="baz">
        Baz

Then list(emphasis.traverse()) equals

[<emphasis>, <strong>, <#text: Foo>, <#text: Bar>]

and list(strong.traverse(ascend=True)) equals

[<strong>, <#text: Foo>, <#text: Bar>, <reference>, <#text: Baz>]
update_all_atts(dict_, update_fun=<function Element.copy_attr_consistent>, replace=True, and_source=False)

Updates all attributes from node or dictionary dict_.

Appends the basic attributes (‘ids’, ‘names’, ‘classes’, ‘dupnames’, but not ‘source’) and then, for all other attributes in dict_, updates the same attribute in self. When attributes with the same identifier appear in both self and dict_, the two values are merged based on the value of update_fun. Generally, when replace is True, the values in self are replaced or merged with the values in dict_; otherwise, the values in self may be preserved or merged. When and_source is True, the ‘source’ attribute is included in the copy.

NOTE: When replace is False, and self contains a ‘source’ attribute,

‘source’ is not replaced even when dict_ has a ‘source’ attribute, though it may still be merged into a list depending on the value of update_fun.

NOTE: It is easier to call the update-specific methods then to pass

the update_fun method to this function.

update_all_atts_coercion(dict_, replace=True, and_source=False)

Updates all attributes from node or dictionary dict_.

Appends the basic attributes (‘ids’, ‘names’, ‘classes’, ‘dupnames’, but not ‘source’) and then, for all other attributes in dict_, updates the same attribute in self. When attributes with the same identifier appear in both self and dict_ whose values are both not lists and replace is True, the values in self are replaced with the values in dict_; if either of the values from self and dict_ for the given identifier are of list type, then first any non-lists are converted to 1-element lists and then the two lists are concatenated and the result stored in self; otherwise, the values in self are preserved. When and_source is True, the ‘source’ attribute is included in the copy.

NOTE: When replace is False, and self contains a ‘source’ attribute,

‘source’ is not replaced even when dict_ has a ‘source’ attribute, though it may still be merged into a list depending on the value of update_fun.

update_all_atts_concatenating(dict_, replace=True, and_source=False)

Updates all attributes from node or dictionary dict_.

Appends the basic attributes (‘ids’, ‘names’, ‘classes’, ‘dupnames’, but not ‘source’) and then, for all other attributes in dict_, updates the same attribute in self. When attributes with the same identifier appear in both self and dict_ whose values aren’t each lists and replace is True, the values in self are replaced with the values in dict_; if the values from self and dict_ for the given identifier are both of list type, then the two lists are concatenated and the result stored in self; otherwise, the values in self are preserved. When and_source is True, the ‘source’ attribute is included in the copy.

NOTE: When replace is False, and self contains a ‘source’ attribute,

‘source’ is not replaced even when dict_ has a ‘source’ attribute, though it may still be merged into a list depending on the value of update_fun.

update_all_atts_consistantly(dict_, replace=True, and_source=False)

Updates all attributes from node or dictionary dict_.

Appends the basic attributes (‘ids’, ‘names’, ‘classes’, ‘dupnames’, but not ‘source’) and then, for all other attributes in dict_, updates the same attribute in self. When attributes with the same identifier appear in both self and dict_ and replace is True, the values in self are replaced with the values in dict_; otherwise, the values in self are preserved. When and_source is True, the ‘source’ attribute is included in the copy.

NOTE: When replace is False, and self contains a ‘source’ attribute,

‘source’ is not replaced even when dict_ has a ‘source’ attribute, though it may still be merged into a list depending on the value of update_fun.

update_all_atts_convert(dict_, and_source=False)

Updates all attributes from node or dictionary dict_.

Appends the basic attributes (‘ids’, ‘names’, ‘classes’, ‘dupnames’, but not ‘source’) and then, for all other attributes in dict_, updates the same attribute in self. When attributes with the same identifier appear in both self and dict_ then first any non-lists are converted to 1-element lists and then the two lists are concatenated and the result stored in self; otherwise, the values in self are preserved. When and_source is True, the ‘source’ attribute is included in the copy.

NOTE: When replace is False, and self contains a ‘source’ attribute,

‘source’ is not replaced even when dict_ has a ‘source’ attribute, though it may still be merged into a list depending on the value of update_fun.

update_basic_atts(dict_)

Update basic attributes (‘ids’, ‘names’, ‘classes’, ‘dupnames’, but not ‘source’) from node or dictionary dict_.

walk(visitor)

Traverse a tree of Node objects, calling the dispatch_visit() method of visitor when entering each node. (The walkabout() method is similar, except it also calls the dispatch_departure() method before exiting each node.)

This tree traversal supports limited in-place tree modifications. Replacing one node with one or more nodes is OK, as is removing an element. However, if the node removed or replaced occurs after the current node, the old node will still be traversed, and any new nodes will not.

Within visit methods (and depart methods for walkabout()), TreePruningException subclasses may be raised (SkipChildren, SkipSiblings, SkipNode, SkipDeparture).

Parameter visitor: A NodeVisitor object, containing a visit implementation for each Node subclass encountered.

Return true if we should stop the traversal.

walkabout(visitor)

Perform a tree traversal similarly to Node.walk() (which see), except also call the dispatch_departure() method before exiting each node.

Parameter visitor: A NodeVisitor object, containing a visit and depart implementation for each Node subclass encountered.

Return true if we should stop the traversal.

runthis.sphinxext.setup(app)
runthis.sphinxext.visit_runthis_html(self, node, app=None)

Visit runthis code block