sphinx_c_autodoc.viewcode package#

Module contents#

Handles viewcode for c.

The processing idea:

  1. Walk through every node in the document finding out if it is a C construct. Then find out which file, if any it is associated with:

    1. Create a pending cross reference to the file.

    2. Add the file to the environment list of files to create source listings of, app.env._viewcode_c_modules

  2. Walk through all of the files in the environment list, app.env._viewcode_c_modules and create a source listing for each one.

  3. Process the pending cross references and link them up to the source listings.

Note

The environment attribute is namespaced with c to prevent populating the viewcode extension’s variable for multi-language documentation purposes.

class sphinx_c_autodoc.viewcode.DocumentationReference(docname: str, module: str, fullname: str)[source]#

Bases: object

Representation of the documentation of a C construct.

docname#

The document which contains the documentation of the C construct.

Type:

str

module#

The c module, this is relative to a path in LINK_TO_SOURCE_ROOTS

Type:

str

fullname#

The name of the construct, i.e. function name, variable name etc.

Type:

str

docname: str#
fullname: str#
module: str#
sphinx_c_autodoc.viewcode.add_source_listings(app: Sphinx) → Iterator[Tuple[str, Dict[str, Any], str]][source]#

The idea is to create a code listing of each source file that has a pending cross reference to.

The pending source files to create listings for are stored in app.env._viewcode_c_modules.

Meant to be connected to the html-collect-pages event, https://www.sphinx-doc.org/en/master/extdev/appapi.html#event-html-collect-pages

Parameters:

app – The current sphinx app being run.

Yields:

Tuple[str, Dict[str, Any], str] – The name of the page, the contents of the page, the name of the template to use for generating the final page.

sphinx_c_autodoc.viewcode.doctree_read(app: Sphinx, doctree: Node) → None[source]#

Go through the entire document looking for C signature nodes to create cross references to the actual source listings.

Parameters:

  • app (Sphinx) – The sphinx app currently doing the processing.

  • doctree (Node) – The root node of the document to walk through. This will be modified in place, by modifiying signature nodes of C constructs.

sphinx_c_autodoc.viewcode.missing_reference(app: Sphinx, env: BuildEnvironment, node: Element, contnode: Node) → Node | None[source]#

Adds a reference node to and c viewcode links which haven’t been resolved yet.

If the location to cross reference does not exist this will return an empty node.

Parameters:

  • app (Sphinx) – The currently running sphinx application.

  • env (BuildEnvironment) – The current build environment.

  • node (Element) – The node which is a pending cross reference.

  • contnode (Node) – The _contents_ node of the created cross reference

Returns:

The cross refernce node to use.

sphinx_c_autodoc.viewcode.setup(app: Sphinx) → None[source]#

Setup function for registering this with sphinx

Parameters:

app (Sphinx) – The application for the current run of sphinx.