sphinxcontrib.towncrier package

Submodules

• sphinxcontrib.towncrier._towncrier module
• sphinxcontrib.towncrier._version module

Module contents

Sphinx extension for injecting an unreleased changelog into docs.

class sphinxcontrib.towncrier.TowncrierDraftEntriesDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: sphinx.util.docutils.SphinxDirective

Definition of the towncrier-draft-entries directive.

has_content = True

May the directive have content?

run() → List[docutils.nodes.Node]

Generate a node tree in place of the directive.

class sphinxcontrib.towncrier.TowncrierDraftEntriesEnvironmentCollector

Bases: sphinx.environment.collectors.EnvironmentCollector

Environment collector for TowncrierDraftEntriesDirective.

When TowncrierDraftEntriesDirective is used in a document, it depends on some dynamically generated change fragments. After the first render, the doctree nodes are put in cache and are reused from there. There’s a way to make Sphinx aware of the directive dependencies by calling BuildEnvironment.note_dependency but this will only work for fragments that have existed at the time of that first directive invocation.

In order to track newly appearing change fragment dependencies, we need to do so at the time of Sphinx identifying what documents require rebuilding. There’s env-get-outdated that allows to extend this list of planned rebuilds and we could use it by assigning a document-to-fragments map from within the directive and reading it in the event handler later (since env contents are preserved in cache). But this approach does not take into account cleanups and parallel runs of Sphinx. In order to make it truly parallelism-compatible, we need to define how to merge our custom cache attribute collected within multiple Sphinx subprocesses into one object and that’s where EnvironmentCollector comes into play.

Refs: * https://github.com/sphinx-doc/sphinx/issues/8040#issuecomment-671587308 * https://github.com/sphinx-contrib/sphinxcontrib-towncrier/issues/1

clear_doc(app: sphinx.application.Sphinx, env: sphinx.environment.BuildEnvironment, docname: str) → None

Clean up env metadata related to the removed document.

This is a handler for env-purge-doc.

get_outdated_docs(app: sphinx.application.Sphinx, env: sphinx.environment.BuildEnvironment, added: Set[str], changed: Set[str], removed: Set[str]) → List[str]

Mark docs with changed fragment deps for rebuild.

This is a handler for env-get-outdated.

merge_other(app: sphinx.application.Sphinx, env: sphinx.environment.BuildEnvironment, docnames: Set[str], other: sphinx.environment.BuildEnvironment) → None

Merge doc-to-fragments from another proc into this env.

This is a handler for env-merge-info.

process_doc(app: sphinx.application.Sphinx, doctree: docutils.nodes.document) → None

React to doctree-read with no-op.

sphinxcontrib.towncrier._get_changelog_draft_entries(target_version: str, allow_empty: bool = False, working_dir: str = None, config_path: str = None) → str

Retrieve the unreleased changelog entries from Towncrier.

sphinxcontrib.towncrier._get_draft_version_fallback(strategy: str, sphinx_config: sphinx.config.Config) → str

Generate a fallback version string for towncrier draft.

sphinxcontrib.towncrier._lookup_towncrier_fragments(working_dir: str = None, config_path: str = None) → Set[pathlib.Path]

Emit RST-formatted Towncrier changelog fragment paths.

sphinxcontrib.towncrier._nodes_from_rst(state: docutils.statemachine.State, rst_source: str) → List[docutils.nodes.Node]

Turn an RST string into a list of nodes.

These nodes can be used in the document.

sphinxcontrib.towncrier.setup(app: sphinx.application.Sphinx) → Dict[str, Union[bool, str]]

Initialize the extension.