sphinx_c_autodoc package#

Subpackages#

Submodules#

sphinx_c_autodoc.loader module#

Load the c file objects

sphinx_c_autodoc.loader.ALLOWED_ANONYMOUS = (CursorKind.ENUM_DECL,)#: Nodes which can be anonymous and still need to be documented. i.e. anonymous structures are usually part of another node. Anonymous enums are often used to use the enumerators but not force the type usage.

sphinx_c_autodoc.loader.DOCUMENTATION_COMMENT_START = ('/**', '/*!', '///')#: The first few characters of a comment which indicates a documentation comment.

class sphinx_c_autodoc.loader.DocumentedEnum(node: Cursor)[source]#

Bases: DocumentedStructure

Class for Enums. Same as structures with a different type.

type_ = 'enum'#

class sphinx_c_autodoc.loader.DocumentedEnumerator(node: Cursor)[source]#

Bases: DocumentedObject

An enumerator, the constant values in an enum

format_name() → str[source]#

The name of the object.

For things like functions and others this will include the return type.

type_ = 'enumerator'#

class sphinx_c_autodoc.loader.DocumentedFile(node: Cursor)[source]#

Bases: DocumentedObject

A documented file

type_ = 'file'#

class sphinx_c_autodoc.loader.DocumentedFunction(node: Cursor)[source]#

Bases: DocumentedObject

A function specific documented object.

format_args(**kwargs: Any) → str[source]#: Creates the parenthesis version of the function signature. i.e. this will be the (int hello, int what) portion of the function header.

format_name() → str[source]#

Format the name of self.object.

This normally should be something that can be parsed by the generated directive, but doesn’t need to be (Sphinx will display it unparsed then).

For things like functions and others this will include the return type.

get_doc() → str[source]#: Get the documentation paragraph of the item

get_parsed_declaration() → str[source]#: Creates the parenthesis version of the function signature. i.e. this will be the (int hello, int what) portion of the header.

get_soup_doc() → str | None[source]#: Gets the documentation from the _soup.

is_public() → bool[source]#: Functions are public as long as they are not static.

type_ = 'function'#

class sphinx_c_autodoc.loader.DocumentedMacro(node: Cursor)[source]#

Bases: DocumentedObject

A documented macro

format_args(**kwargs: Any) → str[source]#

If the macro is function like, gets the parenthesis version of the function signature. i.e. this will be the (_x, _y) portion of the macro function header. Otherwise this is the empty string.

Returns:: The argument string for this macro.

format_name() → str[source]#

Format the name for use in sphinx.

For things like functions and others this will include the return type.

get_parsed_declaration() → str[source]#: Creates the full declaration of the macro. For function like macros this will include the parenthesised arguments.

type_ = 'macro'#

class sphinx_c_autodoc.loader.DocumentedMember(node: Cursor)[source]#

Bases: DocumentedObject

A documented member of a struct or union.

get_parsed_declaration() → str[source]#

Build up the name from the node. This should be the member’s type and it’s name. i.e. for:

struct foo
{
    int bar;
    float hello;
};

The parsed declaration of bar would be int bar.

is_public() → bool[source]#: Members are always public, because it’s their parents that determine public versus private.

type_ = 'member'#

class sphinx_c_autodoc.loader.DocumentedObject(node: Cursor)[source]#

Bases: object

A representation of a c object for documentation purposes.

Parameters:: node (Cursor) – The node representing this object.

type_#

The type of this item one of:

object: unknown/unsupported object.
file: Should be the root object of a documentation tree.
member: Member or field of a struct or union
function: A function
type: A typedef
struct: A structure
union: A Union
enumerator: An enumerator constant
macro: A macro

Type:: str

doc#

The default documentation of the object. This is usally the comment with leading ‘*’ removed.

Type:: str

name#

The name of the object. For example functions this would be only the name of the function.

Type:: str

node#

The node representing this object.

Type:: Cursor

_children#: The children of the object. For example for structs this would be the members or fields.

_soup#

The soupified version of node’s clang xml comment.

Type:: BeautifulSoup

_declaration#

The declaration string. For most things this is the type as well as the name.

Type:: str

_line_range#

The line range of the C construct, this will include any leading or trailing comments that may be part of the construct’s documentation.

Type:: Tuple[int, int]

property children: dict#: The child objects of this object.

property declaration: str#: Declaration for this object. For things like functions it will be void foo(int a, int b) for variables it will be the type and name char my_var.

format_args(**kwargs: Any) → str[source]#: Creates the parenthesis version of the function signature. i.e. this will be the (int hello, int what) portion of a function.

format_name() → str[source]#

The name of the object.

For things like functions and others this will include the return type.

get_doc() → str[source]#: Get the documentation paragraph of the item

static get_paragraph(tag: Tag | None) → str[source]#

Get the paragraph contents from tag.

Parameters:

tag (tag) – The tag to get the paragraph contents from.

Returns:

One of two things:

An empty string if tag is None.
All of the paragraph contents of tag with newlines between them along with a trailing newline, otherwise.

Return type:

str

get_parsed_declaration() → str[source]#: Get the declaration as parsed from the node. This may be specific to each type.

get_soup_declaration() → str | None[source]#: Get the declaration element from soup. If there is no soup or no declaration this will return None.

is_public() → bool[source]#

Determines if this item is public.

C doesn’t actually have public/private namespace so we’re going to make up some rules.

Constructs are public if:

They are in a header file. By nature header files are meant to be included in other files, thus they are deamed public.

They can be visible outside of the compilation unit. These are things the linker can get access to. Mainly this means functions and variables that are not static.

line_range() → Tuple[int, int][source]#

The lines in the source file that this object covers.

This will include any leading or trailing comments that may be part of the construct’s documentation.

property soup: BeautifulSoup | None#

Get the beautifulsoup representation of this object’s comment.

Returns:: The xml comment for this C object turned into soup.
Return type:: BeautifulSoup

property type: str#: The type of object

type_ = 'object'#

class sphinx_c_autodoc.loader.DocumentedStructure(node: Cursor)[source]#

Bases: DocumentedObject

A documented structure

property children: dict#: Gets the children, members, of the structure.

get_parsed_declaration() → str[source]#: Structures, and similar, are just name.

property soup: None#

“ and “Enumerators:” sections do not use the clang xml comments as they don’t preserve newlines, so the sections get lost.

Type:: Since structures like objects use the “Members

type_ = 'struct'#

class sphinx_c_autodoc.loader.DocumentedType(node: Cursor)[source]#

Bases: DocumentedObject

A documented type(def)

get_parsed_declaration() → str[source]#

Format the name of self.object.

This normally should be something that can be parsed by the generated directive, but doesn’t need to be (Sphinx will display it unparsed then).

For things like functions and others this will include the return type.

type_ = 'type'#

class sphinx_c_autodoc.loader.DocumentedUnion(node: Cursor)[source]#

Bases: DocumentedStructure

Class for unions. Same as structures with a different type.

type_ = 'union'#

class sphinx_c_autodoc.loader.DocumentedVariable(node: Cursor)[source]#

Bases: DocumentedObject

Class for file level variables

format_name() → str[source]#

Format the name of self.object.

This normally should be something that can be parsed by the generated directive, but doesn’t need to be (Sphinx will display it unparsed then).

For things like functions and others this will include the return type.

get_parsed_declaration() → str[source]#: Get the declaration as parsed from the node.

is_public() → bool[source]#: Variables are public as long as they are not static.

type_ = 'variable'#

class sphinx_c_autodoc.loader.PsuedoToken(spelling, extent)#

Bases: tuple

A light container to mimic a cindex.Token for comments.

extent#: Alias for field number 1

spelling#: Alias for field number 0

sphinx_c_autodoc.loader.TRAILING_COMMENT_START = ('/**<', '/*!<', '///<')#: The start of a comment that is meant to document the previous item

sphinx_c_autodoc.loader.UNDOCUMENTED_NODES = (CursorKind.MACRO_DEFINITION,)#: Nodes which clang doesn’t autopopulate with the associated comment

sphinx_c_autodoc.loader.comment_node(node: Cursor | None, token: Token, trailing: bool = False) → None[source]#

Add the comment, token, to the node.

node will be unmodified if:

node is not one of the UNDOCUMENTED_NODE

token is not a documentation comment.

Parameters:

node (Cursor) – The node to attempt to comment.
token (Token) – The token to use for the commenting.
trailing (bool) – Only comment node if token is a trailing comment, TRAILING_COMMENT_START. If False then only comment node if token is a non trailing documentation comment.

sphinx_c_autodoc.loader.comment_nodes(cursor: Cursor, children: List[Cursor]) → None[source]#

Comment all nodes in cursor and children that fall into the UNDOCUMENTED_NODES type of nodes.

The nodes will be modified in place.

Parameters:

cursor (cindex.Cursor) – The parent cursor of the child nodes which may need to be commented. This is assumed to be the root file cursor.
children (Sequence(cindex.Cursor)) – The child nodes which may need to be commented.

sphinx_c_autodoc.loader.get_compilation_args(filename: str, compilation_database: str | None = None) → List[str][source]#

Get the compilation args for filename for the compilation database found in compilation_db_dir

Parameters:

filename (str) – The file to get the compilation arguments for.
compilation_database (str) – The compilation database.

Returns:

The compilation arguments.

Return type:

list[str]

sphinx_c_autodoc.loader.get_file_comment(cursor: Cursor, child: Cursor | None) → str[source]#

Attempts to get the comment at the top of the file.

Parameters:

cursor (cindex.Cursor) – The root cursor of the file.
child (cindex.Cursor) – The first child node in the file. This can be None.

Returns:

The file level comment.

Return type:

str

sphinx_c_autodoc.loader.get_nested_node(cursor: Cursor) → Cursor[source]#: Retrieve the nested node that cursor may be shadowing

sphinx_c_autodoc.loader.load(filename: str, contents: str, compilation_database: str | None = None, compilation_args: Sequence[str] | None = None) → DocumentedObject[source]#

Load a C file into a tree of DocumentedObject’s

Parameters:

filename (str) – The c file to load into a documented item
contents (str) – The contents of filename
compilation_database (str) – The compilation database.
compilation_args (str) – Compilation arguments. Will be applied after compilation database.

Returns:

The documented version of filename.

Return type:

DocumentedObject

sphinx_c_autodoc.loader.object_from_cursor(cursor: Cursor) → DocumentedObject | None[source]#: Create an instance from a cindex.Cursor

sphinx_c_autodoc.loader.parse_comment(comment: Token | PsuedoToken) → str[source]#

Clean up a C comment such that it no longer has leading /**, leading lines of * or trailing */

Parameters:: comment (cindex.Token) – A c comment token from clang.
Returns:: The comment with the c comment syntax removed.
Return type:: str

Module contents#

sphinx_c_autodoc is a package which provide c source file parsing for sphinx.

It is composed of multiple directives and settings:

.. c:module:: filename#: A directive to document a c file. This is similar to py:module except it’s for the C domain. This can be used for both c source files as well as c header files.

class sphinx_c_autodoc.CDataDocumenter(directive: DocumenterBridge, name: str, indent: str = '')[source]#

Bases: CObjectDocumenter

The documenter for the autocdata directive.

classmethod can_document_member(member: Any, membername: str, isattr: bool, parent: Any) → bool[source]#

Parameters:

member (object) – The member item to document. This type is specific to the item being processed by autodoc. These classes will only attempt to process sphinx_c_autodoc.loader.CObjectDocumenter members.
membername (str) – The name of the item to document. For example if this is a function then this will be the name of the function, no return types, no arguments.
isattr (bool) – Is the member an attribute. This is unused for c documenation.
parent (object) – The parent item of this member.

Returns:

True if this class can document the member.

Return type:

bool

directivetype = 'var'#

objtype = 'cdata'#: name by which the directive is called (auto…) and the default generated directive name

class sphinx_c_autodoc.CEnumDocumenter(directive: DocumenterBridge, name: str, indent: str = '')[source]#

Bases: CTypeDocumenter

The documenter for the autocenum directive.

directivetype = 'enum'#

objtype = 'cenum'#: name by which the directive is called (auto…) and the default generated directive name

class sphinx_c_autodoc.CEnumeratorDocumenter(directive: DocumenterBridge, name: str, indent: str = '')[source]#

Bases: CObjectDocumenter

The documenter for the autocenumerator directive. These are enumerator constants, versus the enum (type).

directivetype = 'enumerator'#

objtype = 'cenumerator'#: name by which the directive is called (auto…) and the default generated directive name

class sphinx_c_autodoc.CFunctionDocumenter(directive: DocumenterBridge, name: str, indent: str = '')[source]#

Bases: CObjectDocumenter

The documenter for the autocfunction directive.

directivetype = 'function'#

objtype = 'cfunction'#: name by which the directive is called (auto…) and the default generated directive name

class sphinx_c_autodoc.CMacroDocumenter(directive: DocumenterBridge, name: str, indent: str = '')[source]#

Bases: CObjectDocumenter

The documenter for the autocmacro directive.

directivetype = 'macro'#

objtype = 'cmacro'#: name by which the directive is called (auto…) and the default generated directive name

class sphinx_c_autodoc.CMemberDocumenter(directive: DocumenterBridge, name: str, indent: str = '')[source]#

Bases: CObjectDocumenter

The documenter for the autocmember directive.

This handles structure and union fields.

directivetype = 'member'#

objtype = 'cmember'#: name by which the directive is called (auto…) and the default generated directive name

class sphinx_c_autodoc.CModule(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]#

Bases: CObject

Module directive for C files

has_content = True#: May the directive have content?

object_type = 'module'#

required_arguments = 1#: Number of required directive arguments.

run() → List[Node][source]#: Not sure yet

class sphinx_c_autodoc.CModuleDocumenter(directive: DocumenterBridge, name: str, indent: str = '')[source]#

Bases: CObjectDocumenter

This auto documenter will be registered as a directive named autocmodule, there may be a way to override the python automodule, just not sure yet…

classmethod can_document_member(member: Any, membername: str, isattr: bool, parent: Any) → bool[source]#

Modules are top levels so should never be included as a child of another c object.

Parameters:

member (object) – The member item to document. This type is specific to the item being processed by autodoc. These instances will only attempt to process sphinx_c_autodoc.loader.CObjectDocumenter.
membername (str) – The name of the item to document. For example if this is a function then this will be the name of the function, no return types, no arguments.
isattr (bool) – Is the member an attribute. This is unused for c documenation.
parent (object) – The parent item of this member.

Returns:

True if this class can document the member.

Return type:

bool

directivetype = 'module'#

objtype = 'cmodule'#: name by which the directive is called (auto…) and the default generated directive name

class sphinx_c_autodoc.CObjectDocumenter(directive: DocumenterBridge, name: str, indent: str = '')[source]#

Bases: Documenter

A C object autodocument class to work with autodoc extension for sphinx.

classmethod can_document_member(member: Any, membername: str, isattr: bool, parent: Any) → bool[source]#

Parameters:

member (object) – The member item to document. This type is specific to the item being processed by autodoc. These classes will only attempt to process sphinx_c_autodoc.loader.CObjectDocumenter members.
membername (str) – The name of the item to document. For example if this is a function then this will be the name of the function, no return types, no arguments.
isattr (bool) – Is the member an attribute. This is unused for c documenation.
parent (object) – The parent item of this member.

Returns:

True if this class can document the member.

Return type:

bool

directivetype = 'object'#

domain = 'c'#

filter_members(members: List[Tuple[str, Any]], want_all: bool) → List[Tuple[str, Any, bool]][source]#

Filter the given member list.

filter_members() is called after get_object_members(), this means if want_all is False then only private members which were explicitly requested will be in this list. Only when want_all is True do we need to actually condition on private member.

Members are skipped if

they are private (except if given explicitly or the private-members option is set)
they are undocumented (except if the undoc-members option is set)

TODO not implemented yet. The user can override the skipping decision by connecting to the autodoc-skip-member event.

format_args(**kwargs: Any) → str[source]#: Creates the parenthesis version of the function signature. i.e. this will be the (int hello, int what) portion of the header.

format_name() → str[source]#

Format the name of self.object.

This normally should be something that can be parsed by the generated directive, but doesn’t need to be (Sphinx will display it unparsed then).

For things like functions and others this will include the return type.

get_compilation_database() → str | None[source]#

Get’s the compilation database from the environment c_autodoc_compilation_database

Returns:

The full path to the compilation database to use. None if there is no: compilation database.

Return type:

str

get_doc() → List[List[str]] | None[source]#: Decode and return lines of the docstring(s) for the object.

get_object_members(want_all: bool) → Tuple[bool, List[Any]][source]#

Return (members_check_module, members) where members is a list of (membername, member) pairs of the members of self.object.

If want_all is True, return all members. Else, only return those members given by self.options.members (which may also be none).

import_object(raiseerror: bool = False) → bool[source]#

Load the C file and build up the document structure.

This will load the C file’s documented structure into object

Parameters:: raiseerror (bool) – Raise error, this is ignored for the c implementation as import errors don’t happen.
Returns:: True if the file was imported, false otherwise.
Return type:: bool

option_spec: OptionSpec = {'member-order': <function member_order_option>, 'members': <function members_option>, 'noindex': <function bool_option>, 'private-members': <function bool_option>, 'undoc-members': <function bool_option>}#

parse_name() → bool[source]#

Determine what module to import and what attribute to document.

Note

Sphinx autodoc supports args and return anotation, since this is targeting C and it isn’t currently needed, these won’t be supported by this implementation.

Returns:

True if successfully parsed and sets modname,

objpath, fullname.

False if the signature couldn’t be parsed.

Return type:

bool

priority = 11#: priority if multiple documenters return True from can_document_member

resolve_name(modname: str | None, parents: List[str], path: str | None, base: str) → Tuple[str | None, List[str]][source]#

Resolve the module and object name of the object to document. This can be derived in two ways:

Naked: Where the argument is only the file/module name my_file.c
Double colons: Where the argument to the directive is of the form my_file.c::some_func.

Parameters:

modname (str) – The filename of the c file (module)
parents (list) –
The list split(‘.’) version of path.
- The filename without the extension when naked argument is used.
- Any parents when double colon argument is used. For example structs or unions of my_struct.field_name would have a parents entry of [‘my_struct’]
path (str) –
Two possible states:
- None if parents is the empty list.
- The '.'.join() version of parents, with a trailing ..
base (str) – The name of the object to document. This will be None when the object to document is the c module

Returns:

(str, [str]) The module name, and the object names (if any).

Return type:

tuple

class sphinx_c_autodoc.CStructDocumenter(directive: DocumenterBridge, name: str, indent: str = '')[source]#

Bases: CTypeDocumenter

The documenter for the autocstruct directive.

analyzer: ModuleAnalyzer#

args: str#

config: Config#

directivetype = 'struct'#

env: BuildEnvironment#

filter_members(members: List[Tuple[str, Any]], want_all: bool) → List[Tuple[str, Any, bool]][source]#

Filter the given member list.

For structures if they are documented then all members provided are documented.

fullname: str#

modname: str#

module: ModuleType#

object: Any#

object_name: str#

objpath: list[str]#

objtype = 'cstruct'#: name by which the directive is called (auto…) and the default generated directive name

parent: Any#

retann: str#

class sphinx_c_autodoc.CTypeDocumenter(directive: DocumenterBridge, name: str, indent: str = '')[source]#

Bases: CObjectDocumenter

The documenter for the autoctype directive.

analyzer: ModuleAnalyzer#

args: str#

config: Config#

consolidate_members() → StringList[source]#

Take any duplicate autodoc member directives and consolidate them into one directive. The subsequent contents of duplicate directives will be added as additional paragraphs on the first occurrence of the directive.

Returns:: The entire rst contents for this directive instance.
Return type:: StringList

directivetype = 'type'#

env: BuildEnvironment#

format_name() → str[source]#

Format the name of self.object.

Sphinx doesn’t like the typedef keyword being in typedef signatures so strip them off here.

fullname: str#

generate(more_content: StringList | None = None, real_modname: str | None = None, check_module: bool = False, all_members: bool = False) → None[source]#: generate stuff

modname: str#

module: ModuleType#

object: Any#

object_name: str#

objpath: list[str]#

objtype = 'ctype'#: name by which the directive is called (auto…) and the default generated directive name

parent: Any#

retann: str#

class sphinx_c_autodoc.CUnionDocumenter(directive: DocumenterBridge, name: str, indent: str = '')[source]#

Bases: CStructDocumenter

The documenter for the autocunion directive.

analyzer: ModuleAnalyzer#

args: str#

config: Config#

directivetype = 'union'#

env: BuildEnvironment#

fullname: str#

modname: str#

module: ModuleType#

object: Any#

object_name: str#

objpath: list[str]#

objtype = 'cunion'#: name by which the directive is called (auto…) and the default generated directive name

parent: Any#

retann: str#

class sphinx_c_autodoc.ViewCodeListing(raw_listing: str, ast: ~typing.Dict, doc_links: ~typing.Dict = <factory>)[source]#

Bases: object

A data structure used for constructing a viewcode source listing.

raw_listing#

The plain text representation of the code. This should be basically the output of file.read().

Type:: str

ast#

A dictionary like representation of the code constructs. See Common Terms.

Type:: Dict

doc_links#

To be used by the consumers, i.e. viewcode.

Type:: Dict

ast: Dict#

doc_links: Dict#

raw_listing: str#

sphinx_c_autodoc.setup(app: Sphinx) → None[source]#: Setup function for registering this with sphinx