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)¶