lib.publisher

Docutils Publisher fors for Django Docutils.

django_docutils.lib.publisher.publish_parts_from_doctree(document, destination_path=None, writer=None, writer_name='pseudoxml', settings=None, settings_spec=None, settings_overrides=None, config_section=None, enable_exit_status=False)
function[source]
function[source]
django_docutils.lib.publisher.publish_parts_from_doctree(document, destination_path=None, writer=None, writer_name='pseudoxml', settings=None, settings_spec=None, settings_overrides=None, config_section=None, enable_exit_status=False)

Render docutils doctree into docutils parts.

Parameters:

  • document (docutils.nodes.document) – Doctree to sanitize and render.

  • destination_path (str, optional) – Destination path handed to the docutils publisher.

  • writer (docutils.writers.Writer, optional) – Writer instance; writer_name selects one when omitted.

  • writer_name (str) – Writer name used when writer is not given.

  • settings (optional) – Pre-built docutils settings object. The resolved security settings are written onto it, but configuration files it already read cannot be retroactively undone — prefer None.

  • settings_spec (optional) – docutils settings spec passed through to the publisher.

  • settings_overrides (mapping, optional) – Per-call Docutils settings resolved via get_docutils_settings().

  • config_section (str, optional) – docutils configuration section passed through to the publisher.

  • enable_exit_status (bool) – Forwarded to Publisher.publish.

Returns:

docutils parts (e.g. html_body) keyed by part name.

Return type:

dict

Examples

>>> doctree = publish_doctree("Hello **world**")
>>> parts = publish_parts_from_doctree(doctree, writer=DjangoDocutilsWriter())
>>> "world" in parts["html_body"]
True
django_docutils.lib.publisher.publish_toc_from_doctree(doctree, writer=None)
function[source]
function[source]
django_docutils.lib.publisher.publish_toc_from_doctree(doctree, writer=None)

Publish table of contents from docutils doctree.

Parameters:

  • doctree (document)

  • writer (Any | None)

Return type:

str | None

django_docutils.lib.publisher.publish_doctree(source, settings_overrides=None)
function[source]
function[source]
django_docutils.lib.publisher.publish_doctree(source, settings_overrides=None)

Split off ability to get doctree (a.k.a. document).

It’s valuable to be able to run transforms to alter and most importantly, extract data like post abstracts.

Parameters:

  • source (str or bytes) – RST content

  • settings_overrides (dict) – Settings overrides for docutils

Returns:

document/doctree for reStructuredText content

Return type:

docutils.nodes.document

Examples

>>> doctree = publish_doctree("Hello **world**")
>>> doctree.astext().startswith("Hello")
True
class django_docutils.lib.publisher.PublishHtmlDocTreeKwargs
class[source]
class[source]
class django_docutils.lib.publisher.PublishHtmlDocTreeKwargs

Bases: TypedDict

Keyword arguments accepted by publish_html_from_source.

show_title: NotRequired[bool]
attribute
attribute
show_title: NotRequired[bool]
toc_only: NotRequired[bool]
attribute
attribute
toc_only: NotRequired[bool]
django_docutils.lib.publisher.publish_html_from_source(source, **kwargs)
function[source]
function[source]
django_docutils.lib.publisher.publish_html_from_source(source, **kwargs)

Return HTML from reStructuredText source string.

Parameters:
Returns:

Rendered HTML, or None when only an empty TOC was requested.

Return type:

str or None

Examples

>>> html = publish_html_from_source("Hello **world**")
>>> html is not None and "world" in html
True
django_docutils.lib.publisher.publish_html_from_doctree(doctree, show_title=True, toc_only=False)
function[source]
function[source]
django_docutils.lib.publisher.publish_html_from_doctree(doctree, show_title=True, toc_only=False)

Return HTML from reStructuredText document (doctree).

Parameters:

  • doctree (docutils.nodes.document) – reStructuredText document (doctree) to render

  • show_title (bool) – Show top level title

  • toc_only (bool) – Special flag: return show TOC, used for sidebars

Returns:

HTML from reStructuredText document (doctree)

Return type:

str or None

Examples

>>> doctree = publish_doctree("Hello **world**")
>>> html = publish_html_from_doctree(doctree)
>>> html is not None and "<strong>world</strong>" in html
True