API References

Roles and Directives

See also

For a minimal end-to-end example of creating your own directive, start with Extending Directives/Roles.

Base Role Classes

class sphinxnotes.render.BaseContextRole[source]

Bases: BaseContextSource, SphinxRole

This class generates sphinxnotes.render.pending_node in SphinxRole.run() method and makes sure it is rendered correctly.

User should implement current_context and current_template methods to provide the constructor parameters of pending_node.

process_pending_node(n)[source]

This method is called when it is the pending node’s turn to be rendered.

Return true if you want to render the pending node now; otherwise it will be inserted into the doctree directly and wait for later rendering (and this method will be called again.).

You can add hooks to the pending node here, or call queue_pending_node(). You are responsible for inserting created nodes into the doctree yourself.

Note

Please always call super().process_pending_node(n) to ensure the extension functions properly.

Parameters:

n (pending_node)

Return type:

bool

abstractmethod current_context()

Return the context to be rendered.

Return type:

PendingContext | ResolvedContext

abstractmethod current_template()

Return the template for rendering the context.

This method should be implemented to provide the Jinja2 template that will render the context into markup text. The template determines the phase at which rendering occurs.

Returns:

The template to use for rendering.

Return type:

Template

queue_context(ctx, tmpl)

A helper method for queue_pending_node.

Parameters:
Return type:

pending_node

queue_pending_node(n)

Push back a new pending_node to the render queue.

Parameters:

n (pending_node)

Return type:

None

class sphinxnotes.render.BaseDataDefineRole[source]

Bases: BaseRawDataSource, BaseContextRole

abstractmethod current_schema()

Return the schema for constraining the generated :py:class`~sphinxnotes.render.RawData`. see Templating for more details.

Return type:

Schema

abstractmethod current_template()

Return the template for rendering the context.

This method should be implemented to provide the Jinja2 template that will render the context into markup text. The template determines the phase at which rendering occurs.

Returns:

The template to use for rendering.

Return type:

Template

process_pending_node(n)

This method is called when it is the pending node’s turn to be rendered.

Return true if you want to render the pending node now; otherwise it will be inserted into the doctree directly and wait for later rendering (and this method will be called again.).

You can add hooks to the pending node here, or call queue_pending_node(). You are responsible for inserting created nodes into the doctree yourself.

Note

Please always call super().process_pending_node(n) to ensure the extension functions properly.

Parameters:

n (pending_node)

Return type:

bool

queue_context(ctx, tmpl)

A helper method for queue_pending_node.

Parameters:
Return type:

pending_node

queue_pending_node(n)

Push back a new pending_node to the render queue.

Parameters:

n (pending_node)

Return type:

None

Base Directive Classes

class sphinxnotes.render.BaseContextDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Bases: BaseContextSource, SphinxDirective

This class generates sphinxnotes.render.pending_node in SphinxDirective.run() method and makes sure it is rendered correctly.

User should implement current_context and current_template methods to provide the constructor parameters of pending_node.

abstractmethod current_context()

Return the context to be rendered.

Return type:

PendingContext | ResolvedContext

abstractmethod current_template()

Return the template for rendering the context.

This method should be implemented to provide the Jinja2 template that will render the context into markup text. The template determines the phase at which rendering occurs.

Returns:

The template to use for rendering.

Return type:

Template

process_pending_node(n)

This method is called when it is the pending node’s turn to be rendered.

Return true if you want to render the pending node now; otherwise it will be inserted into the doctree directly and wait for later rendering (and this method will be called again.).

You can add hooks to the pending node here, or call queue_pending_node(). You are responsible for inserting created nodes into the doctree yourself.

Note

Please always call super().process_pending_node(n) to ensure the extension functions properly.

Parameters:

n (pending_node)

Return type:

bool

queue_context(ctx, tmpl)

A helper method for queue_pending_node.

Parameters:
Return type:

pending_node

queue_pending_node(n)

Push back a new pending_node to the render queue.

Parameters:

n (pending_node)

Return type:

None

class sphinxnotes.render.BaseDataDefineDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Bases: BaseRawDataSource, BaseContextDirective

User is responsible to implement current_schema method.

current_raw_data()[source]

Return the RawData generating from from directive’s arguments, options, and content, and then it will be parsed by Schema returned from current_schema method.

See Main Context for more details.

Note

In most cases, the default implementation works well and you don’t need to override it.

Return type:

RawData

abstractmethod current_schema()

Return the schema for constraining the generated :py:class`~sphinxnotes.render.RawData`. see Templating for more details.

Return type:

Schema

abstractmethod current_template()

Return the template for rendering the context.

This method should be implemented to provide the Jinja2 template that will render the context into markup text. The template determines the phase at which rendering occurs.

Returns:

The template to use for rendering.

Return type:

Template

process_pending_node(n)

This method is called when it is the pending node’s turn to be rendered.

Return true if you want to render the pending node now; otherwise it will be inserted into the doctree directly and wait for later rendering (and this method will be called again.).

You can add hooks to the pending node here, or call queue_pending_node(). You are responsible for inserting created nodes into the doctree yourself.

Note

Please always call super().process_pending_node(n) to ensure the extension functions properly.

Parameters:

n (pending_node)

Return type:

bool

queue_context(ctx, tmpl)

A helper method for queue_pending_node.

Parameters:
Return type:

pending_node

queue_pending_node(n)

Push back a new pending_node to the render queue.

Parameters:

n (pending_node)

Return type:

None

class sphinxnotes.render.StrictDataDefineDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Bases: BaseDataDefineDirective

classmethod derive(name, schema, tmpl)[source]

Dynamically derive a new directive class from schema and template.

This method generates a new StrictDataDefineDirective subclass with the given schema and template. It automatically sets the appropriate argument counts, option specifications, and content handling based on the schema definition.

Parameters:
Return type:

type[StrictDataDefineDirective]

Node

class sphinxnotes.render.pending_node(ctx, tmpl, inline=False, rawsource='', *children, **attributes)[source]

A docutils node to be rendered.

Parameters:

Context

Context refers to the dynamic content of a Jinja template. It can be:

ResolvedContext:

Our dedicated data type (sphinxnotes.render.ParsedData), or any Python dict.

PendingContext:

Context that is not yet available. For example, it may contain unparsed data, remote data, and more.

PendingContext can be resolved to ResolvedContext by calling resolve().

type sphinxnotes.render.ResolvedContext = ParsedData | dict[str, Any]
class sphinxnotes.render.PendingContext[source]

An abstract representation of context that is not currently available.

abstractmethod resolve()[source]

This method will be called when rendering to get the available ResolvedContext.

Return type:

ResolvedContext

PendingContext Implementations

class sphinxnotes.render.UnparsedData(raw, schema)[source]

Bases: PendingContext

A pending context which contains raw data and its schema.

Raw data will be parsed when calling resolve.

Parameters:

Template

See Templating for the higher-level guide.

class sphinxnotes.render.Template(text: 'str', phase: 'Phase' = <Phase.Parsing: 'parsing'>, debug: 'bool' = False, extra: 'list[str]' = <factory>)[source]
Parameters:
text: str

Jinja template for rendering the context.

phase: Phase = 'parsing'

The render phase.

debug: bool = False

Enable debug output (shown as docutils.nodes.system_message in document.)

extra: list[str]

Names of extra context to be generated and available in the template.

class sphinxnotes.render.Phase(*values)[source]

The phase of rendering template.

Parsing = 'parsing'

Render template on document parsing on (SphinxDirective.run() or SphinxRole.run()).

Parsed = 'parsed'

Render template immediately after document has parsed (on Sphinx event doctree-read).

Resolving = 'resolving'

Render template immediately after all documents have resolving (before Sphinx event doctree-resolved).

Extra Context

See Templating for built-in extra-context names such as doc and sphinx, plus usage examples.

@sphinxnotes.render.extra_context[source]

Decorator to register an extra context.

The phase is determined by which ExtraContext class is used:

GlobalExtraContext

available in all phases

ParsingPhaseExtraContext

available during Parsing phase

ParsedPhaseExtraContext

available during Parsed phase

ResolvingPhaseExtraContext

available during Resolving phase

Example:

@extra_context('doc')
class DocExtraContext(ParsingPhaseExtraContext):
    def generate(self, ctx):
        return proxy(HostWrapper(ctx).doctree)
Parameters:

name (str) – The context name, used in templates via load_extra('name').

class sphinxnotes.render.ParsingPhaseExtraContext[source]

Extra context generated during the Parsing phase. The generate method receives the current directive or role being executed.

phase: ClassVar[Phase | None] = 'parsing'
abstractmethod generate(directive)[source]
Parameters:

directive (SphinxDirective | SphinxRole)

Return type:

Any

class sphinxnotes.render.ParsedPhaseExtraContext[source]

Extra context generated during the Parsed phase. The generate method receives the current Sphinx transform.

phase: ClassVar[Phase | None] = 'parsed'
abstractmethod generate(transform)[source]
Parameters:

transform (SphinxTransform)

Return type:

Any

class sphinxnotes.render.ResolvingPhaseExtraContext[source]

Extra context generated during the Resolving phase. The generate method receives the current Sphinx transform.

phase: ClassVar[Phase | None] = 'resolving'
abstractmethod generate(transform)[source]
Parameters:

transform (SphinxTransform)

Return type:

Any

class sphinxnotes.render.GlobalExtraContext[source]

Extra context available in all phases. The generate method receives the Sphinx build environment.

phase: ClassVar[Phase | None] = None
abstractmethod generate(env)[source]
Parameters:

env (BuildEnvironment)

Return type:

Any

Filters

@sphinxnotes.render.filter[source]

Decorator for adding a filter to the Jinja environment.

Usage:

@filter('my_filter')
def my_filter(env: BuildEnvironment):
    def _filter(value):
        return value.upper()
    return _filter
Parameters:

name (str)

Data, Field and Schema

type sphinxnotes.render.PlainValue = bool | int | float | str | object
type sphinxnotes.render.Value = None | PlainValue | list[PlainValue]
class sphinxnotes.render.RawData(name: 'str | None', attrs: 'dict[str, str]', content: 'str | None')[source]
Parameters:
name: str | None
attrs: dict[str, str]
content: str | None
class sphinxnotes.render.ParsedData(name: 'Value', attrs: 'dict[str, Value]', content: 'Value')[source]
Parameters:

  • name (Value)

  • attrs (dict[str, Value])

  • content (Value)

name: Value
attrs: dict[str, Value]
content: Value
class sphinxnotes.render.Field(etype: 'type' = <class 'str'>, ctype: 'type | None' = None, flags: 'dict[str, Value]'=<factory>, dsl: 'str | None' = None)[source]
Parameters:
parse(rawval)[source]

Parses the raw input string into the target Value. When a None is passed, which means the field is not supplied.

Parameters:

rawval (str | None)

Return type:

Value

class sphinxnotes.render.Schema(name: 'Field | None', attrs: 'dict[str, Field] | Field', content: 'Field | None')[source]
Parameters:
name: Field | None
attrs: dict[str, Field] | Field
content: Field | None
class sphinxnotes.render.data.Registry[source]

Stores supported element types and element forms (containers).

type ByOptionStore = Literal['assign', 'append']
add_type(name, etype, conv, strify, aliases=[])[source]

Register a value type for PlainValue.

Parameters:

  • name (str) – The name for this scalar type, available as a Type modifier in the DSL

  • etype (type) – The Python type object

  • conv (Callable[[str], PlainValue]) – A callable that converts a string to the etype

  • strify (Callable[[PlainValue], str]) – A callable that converts the etype to a string

  • aliases (list[str]) – Alternative names for this type

Return type:

None

See also

Adding Custom Types

add_form(name, ctype, sep, aliases=[])[source]

Register a value form with its container type and separator for Value.

Parameters:

  • name (str) – The name for this form, available as a Form modifier in the DSL

  • ctype (type) – The container type. (for now, it is list, tuple, or set)

  • sep (str) – The separator string used to split/join values

  • aliases (list[str]) – Alternative names for this form

Return type:

None

add_flag(name, default=False, aliases=[])[source]

Register a flag.

Parameters:

  • name (str) – The name for this flag, available as a Flag in the DSL

  • default (bool) – The default value for this flag

  • aliases (list[str]) – Alternative names for this flag

Return type:

None

See also

Adding Custom Flags

add_by_option(name, etype, default=None, store='assign', aliases=[])[source]

Register a by-option.

Parameters:

  • name (str) – The name for this option, available as a By-Option in the DSL

  • etype (type) – The value type for this option

  • default (Value) – The default value for this option

  • store (ByOptionStore) – How to store multiple values

  • aliases (list[str]) – Alternative names for this option

Return type:

None

See also

Adding Custom By-Options

Registry

Developers can extend this extension (for example, to support more data types or add new extra context) by adding new items to sphinxnotes.render.REGISTRY.

sphinxnotes.render.REGISTRY = <sphinxnotes.render.Registry object>

The global, all-in-one registry for users.

class sphinxnotes.render.Registry[source]

The global, all-in-one registry for users.

property data: Registry