a_sync.sphinx package
Submodules
a_sync.sphinx.ext module
Sphinx documentation plugin used to document ASyncFunction instances.
Introduction
Usage
The ez-a-sync extension for Sphinx requires Sphinx 2.0 or later.
Add the extension to your docs/conf.py
configuration module:
extensions = (...,
'a_sync.sphinx.ext')
If you’d like to change the prefix for tasks in reference documentation
then you can change the a_sync_function_prefix
configuration value:
a_sync_function_prefix = '(function)' # < default
a_sync_descriptor_prefix = '(descriptor)' # < default
a_sync_generator_function_prefix = '(genfunc)' # < default
With the extension installed autodoc will automatically find
ASyncFunction objects (e.g. when using the automodule directive)
and generate the correct (as well as add a (function)
prefix),
and you can also refer to the tasks using :task:proj.tasks.add
syntax.
Use .. autotask::
to alternatively manually document a task.
- class a_sync.sphinx.ext.ASyncDescriptorDirective[source]
Bases:
_ASyncMethodDirective
Directive for ASyncDescriptor instances.
- __init__(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)
- _object_hierarchy_parts(sig_node)
Returns a tuple of strings, one entry for each part of the object’s hierarchy (e.g.
('module', 'submodule', 'Class', 'method')
). The returned tuple is used to properly nest children within parents in the table of contents, and can also be used within the_toc_entry_name()
method.This method must not be used outwith table of contents generation.
- _toc_entry_name(sig_node)
Returns the text of the table of contents entry for the object.
This function is called once, in
run()
, to set the name for the table of contents entry (a special attribute_toc_name
is set on the object node, later used inenvironment.collectors.toctree.TocTreeCollector.process_doc().build_toc()
when the table of contents entries are collected).To support table of contents entries for their objects, domains must override this method, also respecting the configuration setting
toc_object_entries_show_parents
. Domains must also override_object_hierarchy_parts()
, with one (string) entry for each part of the object’s hierarchy. The result of this method is set on the signature node, and can be accessed assig_node['_toc_parts']
for use within this method. The resulting tuple is also used to properly nest children within parents in the table of contents.An example implementations of this method is within the python domain (
PyObject._toc_entry_name()
). The python domain sets the_toc_parts
attribute within thehandle_signature()
method.- Parameters:
sig_node (desc_signature)
- Return type:
- add_name(node)
Append self.options[‘name’] to node[‘names’] if it exists.
Also normalize the name string and register it as explicit target.
- add_target_and_index(name_cls, sig, signode)
Add cross-reference IDs and entries to self.indexnode, if applicable.
name is whatever
handle_signature()
returned.
- after_content()
Handle object de-nesting after content
If this class is a nestable object, removing the last nested class prefix ends further nesting in the object.
If this class is not a nestable object, the list of classes should not be altered as we didn’t affect the nesting levels in
before_content()
.- Return type:
None
- assert_has_content()
Throw an ERROR-level DirectiveError if the directive doesn’t have contents.
- before_content()
Handle object nesting before content
PyObject
represents Python language constructs. For constructs that are nestable, such as a Python classes, this method will build up a stack of the nesting hierarchy so that it can be later de-nested correctly, inafter_content()
.For constructs that aren’t nestable, the stack is bypassed, and instead only the most recent object is tracked. This object prefix name will be removed with
after_content()
.- Return type:
None
- debug(message)
- directive_error(level, message)
Return a DirectiveError suitable for being thrown as an exception.
Call “raise self.directive_error(level, message)” from within a directive implementation to return one single system message at level level, which automatically gets the directive block and the line number added.
Preferably use the debug, info, warning, error, or severe wrapper methods, e.g.
self.error(message)
to generate an ERROR-level directive error.
- error(message)
- get_index_text(modname, name_cls)
Return the text for the index entry of the object.
- get_signature_prefix(sig)
Get the signature prefix for the directive.
- Parameters:
sig – The signature to process.
- Returns:
A list of nodes representing the signature prefix.
- Return type:
- get_signatures()
Retrieve the signatures to document from the directive arguments. By default, signatures are given as arguments, one per line.
- handle_signature(sig, signode)
Transform a Python signature into RST nodes.
Return (fully qualified name of the thing, classname if any).
If inside a class, the current class name is handled intelligently: * it is stripped from the displayed name if present * it is added to the full name (return value) if not present
- info(message)
- needs_arglist()
May return true if an empty argument list is to be generated even if the document contains none.
- Return type:
- parse_content_to_nodes(allow_section_headings=False)
Parse the directive’s content into nodes.
- Parameters:
allow_section_headings (bool) – Are titles (sections) allowed in the directive’s content? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of
Structural
nodes, which includesdocument
,section
, andsidebar
nodes.- Return type:
list[Node]
Added in version 7.4.
- parse_inline(text, *, lineno=-1)
Parse text as inline elements.
- Parameters:
- Returns:
A list of nodes (text and inline elements) and a list of system_messages.
- Return type:
Added in version 7.4.
- parse_text_to_nodes(text='', /, *, offset=-1, allow_section_headings=False)
Parse text into nodes.
- Parameters:
text (str) – Text, in string form.
StringList
is also accepted.allow_section_headings (bool) – Are titles (sections) allowed in text? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of
Structural
nodes, which includesdocument
,section
, andsidebar
nodes.offset (int) – The offset of the content.
- Return type:
list[Node]
Added in version 7.4.
- run()
Main directive entry function, called by docutils upon encountering the directive.
This directive is meant to be quite easily subclassable, so it delegates to several additional methods. What it does:
find out if called as a domain-specific directive, set self.domain
create a desc node to fit all description inside
parse standard options, currently no-index
create an index node if needed as self.indexnode
parse all given signatures (as returned by self.get_signatures()) using self.handle_signature(), which should either return a name or raise ValueError
add index entries using self.add_target_and_index()
parse the content and handle doc fields in it
- Return type:
list[Node]
- set_source_info(node)
Set source and line number to the node.
Added in version 2.1.
- Parameters:
node (Node)
- Return type:
None
- severe(message)
- transform_content(content_node)
Called after creating the content through nested parsing, but before the
object-description-transform
event is emitted, and before the info-fields are transformed. Can be used to manipulate the content.- Parameters:
content_node (desc_content)
- Return type:
None
- warning(message)
- allow_nesting = False
- property config: Config
Reference to the
Config
object.Added in version 1.8.
- doc_field_types: list[Field] = [<sphinx.domains.python._object.PyTypedField object>, <sphinx.domains.python._object.PyTypedField object>, <sphinx.domains.python._object.PyGroupedField object>, <sphinx.util.docfields.Field object>, <sphinx.domains.python._object.PyField object>, <sphinx.domains.python._object.PyTypedField object>]
- property env: BuildEnvironment
Reference to the
BuildEnvironment
object.Added in version 1.8.
- final_argument_whitespace = True
May the final argument contain whitespace?
- has_content = True
May the directive have content?
- indexnode: addnodes.index
- option_spec: ClassVar[OptionSpec] = {'abstractmethod': <function flag>, 'annotation': <function unchanged>, 'async': <function flag>, 'canonical': <function unchanged>, 'classmethod': <function flag>, 'final': <function flag>, 'module': <function unchanged>, 'no-contents-entry': <function flag>, 'no-index': <function flag>, 'no-index-entry': <function flag>, 'no-typesetting': <function flag>, 'nocontentsentry': <function flag>, 'noindex': <function flag>, 'noindexentry': <function flag>, 'single-line-parameter-list': <function flag>, 'single-line-type-parameter-list': <function flag>, 'staticmethod': <function flag>}
Mapping of option names to validator functions.
- optional_arguments = 0
Number of optional arguments after the required arguments.
- required_arguments = 1
Number of required directive arguments.
- class a_sync.sphinx.ext.ASyncDescriptorDocumenter[source]
Bases:
_ASyncMethodDocumenter
Document ASyncDescriptor instance definitions.
- typ
alias of
ASyncDescriptor
- __init__(directive, name, indent='')
- add_content(more_content)
Add content from docstrings, attribute documentation and user.
- Parameters:
more_content (StringList | None)
- Return type:
None
- add_directive_header(sig)
Add the directive header and options to the generated content.
- Parameters:
sig (str)
- Return type:
None
- add_line(line, source, *lineno)
Append one line of generated reST to the output.
- annotate_to_first_argument(func, typ)
Annotate type hint to the first argument of function if needed.
- Parameters:
func (Callable)
typ (type)
- Return type:
Callable | None
- classmethod can_document_member(member, membername, isattr, parent)
Determine if the member can be documented by this documenter.
- Parameters:
member – The member to check.
membername – The name of the member.
isattr – Boolean indicating if the member is an attribute.
parent – The parent object.
- Returns:
True if the member can be documented, False otherwise.
- Return type:
- check_module()
Check if the object is defined in the expected module.
- Returns:
True if the object is defined in the expected module, False otherwise.
- Return type:
Note
Normally checks if self.object is really defined in the module given by self.modname. But since functions decorated with the @task decorator are instances living in the celery.local, we have to check the wrapped function instead.
- document_members(all_members=False)
Document members of the object.
- Parameters:
all_members – Boolean indicating if all members should be documented.
- filter_members(members, want_all)
Filter the given member list.
Members are skipped if
they are private (except if given explicitly or the private-members option is set)
they are special methods (except if given explicitly or the special-members option is set)
they are undocumented (except if the undoc-members option is set)
The user can override the skipping decision by connecting to the
autodoc-skip-member
event.
- format_args()
Format the arguments of the wrapped method.
- Returns:
The formatted arguments.
- Return type:
- format_name()
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).
- Return type:
- format_signature(**kwargs)
Format the signature (arguments and return annotation) of the object.
Let the user process it via the
autodoc-process-signature
event.
- generate(more_content=None, real_modname=None, check_module=False, all_members=False)
Generate reST for the object given by self.name, and possibly for its members.
If more_content is given, include that content. If real_modname is given, use that module name to find attribute docs. If check_module is True, only generate if the object is defined in the module name it is imported from. If all_members is True, document all members.
- get_attr(obj, name, *defargs)
getattr() override for types such as Zope interfaces.
- get_doc()
Decode and return lines of the docstring(s) for the object.
When it returns None, autodoc-process-docstring will not be called for this object.
- get_object_members(want_all)
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).
- get_real_modname()
Get the real module name of an object to document.
It can differ from the name of the module through which the object was imported.
- Return type:
- import_object(raiseerror=False)
Import the object given by self.modname and self.objpath and set it as self.object.
Returns True if successful, False if an error occurred.
- merge_default_value(actual, overload)
Merge default values of actual implementation to the overload variants.
- parse_name()
Determine what module to import and what attribute to document.
Returns True and sets self.modname, self.objpath, self.fullname, self.args and self.retann if parsing and resolving was successful.
- Return type:
- process_doc(docstrings)
Let the user process the docstrings before adding them.
- resolve_name(modname, parents, path, base)
Resolve the module and name of the object to document given by the arguments and the current module/class.
Must return a pair of the module name and a chain of attributes; for example, it would return
('zipfile', ['ZipFile', 'open'])
for thezipfile.ZipFile.open
method.
- sort_members(documenters, order)
Sort the given member list.
- content_indent = ' '
indentation by which to indent the directive content
- directivetype = 'method'
- member_order = 50
order if autodoc_member_order is set to ‘groupwise’
- objtype = 'a_sync_descriptor'
name by which the directive is called (auto…) and the default generated directive name
- option_spec: ClassVar[OptionSpec] = {'no-index': <function bool_option>, 'noindex': <function bool_option>}
- priority = 1
priority if multiple documenters return True from can_document_member
- titles_allowed = True
true if the generated content may contain titles
- class a_sync.sphinx.ext.ASyncFunctionAsyncDirective[source]
Bases:
_ASyncFunctionDirective
Directive for ASyncFunctionAsyncDefault instances.
- __init__(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)
- _object_hierarchy_parts(sig_node)
Returns a tuple of strings, one entry for each part of the object’s hierarchy (e.g.
('module', 'submodule', 'Class', 'method')
). The returned tuple is used to properly nest children within parents in the table of contents, and can also be used within the_toc_entry_name()
method.This method must not be used outwith table of contents generation.
- _toc_entry_name(sig_node)
Returns the text of the table of contents entry for the object.
This function is called once, in
run()
, to set the name for the table of contents entry (a special attribute_toc_name
is set on the object node, later used inenvironment.collectors.toctree.TocTreeCollector.process_doc().build_toc()
when the table of contents entries are collected).To support table of contents entries for their objects, domains must override this method, also respecting the configuration setting
toc_object_entries_show_parents
. Domains must also override_object_hierarchy_parts()
, with one (string) entry for each part of the object’s hierarchy. The result of this method is set on the signature node, and can be accessed assig_node['_toc_parts']
for use within this method. The resulting tuple is also used to properly nest children within parents in the table of contents.An example implementations of this method is within the python domain (
PyObject._toc_entry_name()
). The python domain sets the_toc_parts
attribute within thehandle_signature()
method.- Parameters:
sig_node (desc_signature)
- Return type:
- add_name(node)
Append self.options[‘name’] to node[‘names’] if it exists.
Also normalize the name string and register it as explicit target.
- add_target_and_index(name_cls, sig, signode)
Add cross-reference IDs and entries to self.indexnode, if applicable.
name is whatever
handle_signature()
returned.
- after_content()
Handle object de-nesting after content
If this class is a nestable object, removing the last nested class prefix ends further nesting in the object.
If this class is not a nestable object, the list of classes should not be altered as we didn’t affect the nesting levels in
before_content()
.- Return type:
None
- assert_has_content()
Throw an ERROR-level DirectiveError if the directive doesn’t have contents.
- before_content()
Handle object nesting before content
PyObject
represents Python language constructs. For constructs that are nestable, such as a Python classes, this method will build up a stack of the nesting hierarchy so that it can be later de-nested correctly, inafter_content()
.For constructs that aren’t nestable, the stack is bypassed, and instead only the most recent object is tracked. This object prefix name will be removed with
after_content()
.- Return type:
None
- debug(message)
- directive_error(level, message)
Return a DirectiveError suitable for being thrown as an exception.
Call “raise self.directive_error(level, message)” from within a directive implementation to return one single system message at level level, which automatically gets the directive block and the line number added.
Preferably use the debug, info, warning, error, or severe wrapper methods, e.g.
self.error(message)
to generate an ERROR-level directive error.
- error(message)
- get_index_text(modname, name_cls)
Return the text for the index entry of the object.
- get_signature_prefix(sig)
Get the signature prefix for the directive.
- Parameters:
sig – The signature to process.
- Returns:
A list of nodes representing the signature prefix.
- Return type:
- get_signatures()
Retrieve the signatures to document from the directive arguments. By default, signatures are given as arguments, one per line.
- handle_signature(sig, signode)
Transform a Python signature into RST nodes.
Return (fully qualified name of the thing, classname if any).
If inside a class, the current class name is handled intelligently: * it is stripped from the displayed name if present * it is added to the full name (return value) if not present
- info(message)
- needs_arglist()
May return true if an empty argument list is to be generated even if the document contains none.
- Return type:
- parse_content_to_nodes(allow_section_headings=False)
Parse the directive’s content into nodes.
- Parameters:
allow_section_headings (bool) – Are titles (sections) allowed in the directive’s content? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of
Structural
nodes, which includesdocument
,section
, andsidebar
nodes.- Return type:
list[Node]
Added in version 7.4.
- parse_inline(text, *, lineno=-1)
Parse text as inline elements.
- Parameters:
- Returns:
A list of nodes (text and inline elements) and a list of system_messages.
- Return type:
Added in version 7.4.
- parse_text_to_nodes(text='', /, *, offset=-1, allow_section_headings=False)
Parse text into nodes.
- Parameters:
text (str) – Text, in string form.
StringList
is also accepted.allow_section_headings (bool) – Are titles (sections) allowed in text? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of
Structural
nodes, which includesdocument
,section
, andsidebar
nodes.offset (int) – The offset of the content.
- Return type:
list[Node]
Added in version 7.4.
- run()
Main directive entry function, called by docutils upon encountering the directive.
This directive is meant to be quite easily subclassable, so it delegates to several additional methods. What it does:
find out if called as a domain-specific directive, set self.domain
create a desc node to fit all description inside
parse standard options, currently no-index
create an index node if needed as self.indexnode
parse all given signatures (as returned by self.get_signatures()) using self.handle_signature(), which should either return a name or raise ValueError
add index entries using self.add_target_and_index()
parse the content and handle doc fields in it
- Return type:
list[Node]
- set_source_info(node)
Set source and line number to the node.
Added in version 2.1.
- Parameters:
node (Node)
- Return type:
None
- severe(message)
- transform_content(content_node)
Called after creating the content through nested parsing, but before the
object-description-transform
event is emitted, and before the info-fields are transformed. Can be used to manipulate the content.- Parameters:
content_node (desc_content)
- Return type:
None
- warning(message)
- allow_nesting = False
- property config: Config
Reference to the
Config
object.Added in version 1.8.
- doc_field_types: list[Field] = [<sphinx.domains.python._object.PyTypedField object>, <sphinx.domains.python._object.PyTypedField object>, <sphinx.domains.python._object.PyGroupedField object>, <sphinx.util.docfields.Field object>, <sphinx.domains.python._object.PyField object>, <sphinx.domains.python._object.PyTypedField object>]
- property env: BuildEnvironment
Reference to the
BuildEnvironment
object.Added in version 1.8.
- final_argument_whitespace = True
May the final argument contain whitespace?
- has_content = True
May the directive have content?
- indexnode: addnodes.index
- option_spec: ClassVar[OptionSpec] = {'annotation': <function unchanged>, 'async': <function flag>, 'canonical': <function unchanged>, 'module': <function unchanged>, 'no-contents-entry': <function flag>, 'no-index': <function flag>, 'no-index-entry': <function flag>, 'no-typesetting': <function flag>, 'nocontentsentry': <function flag>, 'noindex': <function flag>, 'noindexentry': <function flag>, 'single-line-parameter-list': <function flag>, 'single-line-type-parameter-list': <function flag>}
Mapping of option names to validator functions.
- optional_arguments = 0
Number of optional arguments after the required arguments.
- required_arguments = 1
Number of required directive arguments.
- class a_sync.sphinx.ext.ASyncFunctionAsyncDocumenter[source]
Bases:
_ASyncFunctionDocumenter
Document ASyncFunctionAsyncDefault instance definitions.
- typ
alias of
ASyncFunctionAsyncDefault
- __init__(directive, name, indent='')
- add_content(more_content)
Add content from docstrings, attribute documentation and user.
- Parameters:
more_content (StringList | None)
- Return type:
None
- add_directive_header(sig)
Add the directive header and options to the generated content.
- Parameters:
sig (str)
- Return type:
None
- add_line(line, source, *lineno)
Append one line of generated reST to the output.
- annotate_to_first_argument(func, typ)
Annotate type hint to the first argument of function if needed.
- Parameters:
func (Callable)
typ (type)
- Return type:
Callable | None
- classmethod can_document_member(member, membername, isattr, parent)
Determine if the member can be documented by this documenter.
- Parameters:
member – The member to check.
membername – The name of the member.
isattr – Boolean indicating if the member is an attribute.
parent – The parent object.
- Returns:
True if the member can be documented, False otherwise.
- Return type:
- check_module()
Check if the object is defined in the expected module.
- Returns:
True if the object is defined in the expected module, False otherwise.
- Return type:
Note
Normally checks if self.object is really defined in the module given by self.modname. But since functions decorated with the @task decorator are instances living in the celery.local, we have to check the wrapped function instead.
- document_members(all_members=False)
Document members of the object.
- Parameters:
all_members – Boolean indicating if all members should be documented.
- filter_members(members, want_all)
Filter the given member list.
Members are skipped if
they are private (except if given explicitly or the private-members option is set)
they are special methods (except if given explicitly or the special-members option is set)
they are undocumented (except if the undoc-members option is set)
The user can override the skipping decision by connecting to the
autodoc-skip-member
event.
- format_args()
Format the arguments of the wrapped function.
- Returns:
The formatted arguments.
- Return type:
- format_name()
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).
- Return type:
- format_signature(**kwargs)
Format the signature (arguments and return annotation) of the object.
Let the user process it via the
autodoc-process-signature
event.
- generate(more_content=None, real_modname=None, check_module=False, all_members=False)
Generate reST for the object given by self.name, and possibly for its members.
If more_content is given, include that content. If real_modname is given, use that module name to find attribute docs. If check_module is True, only generate if the object is defined in the module name it is imported from. If all_members is True, document all members.
- get_attr(obj, name, *defargs)
getattr() override for types such as Zope interfaces.
- get_doc()
Decode and return lines of the docstring(s) for the object.
When it returns None, autodoc-process-docstring will not be called for this object.
- get_object_members(want_all)
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).
- get_real_modname()
Get the real module name of an object to document.
It can differ from the name of the module through which the object was imported.
- Return type:
- import_object(raiseerror=False)
Import the object given by self.modname and self.objpath and set it as self.object.
Returns True if successful, False if an error occurred.
- merge_default_value(actual, overload)
Merge default values of actual implementation to the overload variants.
- parse_name()
Determine what module to import and what attribute to document.
Returns True and sets self.modname, self.objpath, self.fullname, self.args and self.retann if parsing and resolving was successful.
- Return type:
- process_doc(docstrings)
Let the user process the docstrings before adding them.
- resolve_name(modname, parents, path, base)
Resolve the module and name of the object to document given by the arguments and the current module/class.
Must return a pair of the module name and a chain of attributes; for example, it would return
('zipfile', ['ZipFile', 'open'])
for thezipfile.ZipFile.open
method.
- sort_members(documenters, order)
Sort the given member list.
- content_indent = ' '
indentation by which to indent the directive content
- member_order = 30
order if autodoc_member_order is set to ‘groupwise’
- objtype = 'a_sync_function_async'
name by which the directive is called (auto…) and the default generated directive name
- option_spec: ClassVar[OptionSpec] = {'no-index': <function bool_option>, 'noindex': <function bool_option>}
- priority = 13
priority if multiple documenters return True from can_document_member
- titles_allowed = True
true if the generated content may contain titles
- class a_sync.sphinx.ext.ASyncFunctionDirective[source]
Bases:
_ASyncFunctionDirective
Directive for ASyncFunction instances.
- __init__(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)
- _object_hierarchy_parts(sig_node)
Returns a tuple of strings, one entry for each part of the object’s hierarchy (e.g.
('module', 'submodule', 'Class', 'method')
). The returned tuple is used to properly nest children within parents in the table of contents, and can also be used within the_toc_entry_name()
method.This method must not be used outwith table of contents generation.
- _toc_entry_name(sig_node)
Returns the text of the table of contents entry for the object.
This function is called once, in
run()
, to set the name for the table of contents entry (a special attribute_toc_name
is set on the object node, later used inenvironment.collectors.toctree.TocTreeCollector.process_doc().build_toc()
when the table of contents entries are collected).To support table of contents entries for their objects, domains must override this method, also respecting the configuration setting
toc_object_entries_show_parents
. Domains must also override_object_hierarchy_parts()
, with one (string) entry for each part of the object’s hierarchy. The result of this method is set on the signature node, and can be accessed assig_node['_toc_parts']
for use within this method. The resulting tuple is also used to properly nest children within parents in the table of contents.An example implementations of this method is within the python domain (
PyObject._toc_entry_name()
). The python domain sets the_toc_parts
attribute within thehandle_signature()
method.- Parameters:
sig_node (desc_signature)
- Return type:
- add_name(node)
Append self.options[‘name’] to node[‘names’] if it exists.
Also normalize the name string and register it as explicit target.
- add_target_and_index(name_cls, sig, signode)
Add cross-reference IDs and entries to self.indexnode, if applicable.
name is whatever
handle_signature()
returned.
- after_content()
Handle object de-nesting after content
If this class is a nestable object, removing the last nested class prefix ends further nesting in the object.
If this class is not a nestable object, the list of classes should not be altered as we didn’t affect the nesting levels in
before_content()
.- Return type:
None
- assert_has_content()
Throw an ERROR-level DirectiveError if the directive doesn’t have contents.
- before_content()
Handle object nesting before content
PyObject
represents Python language constructs. For constructs that are nestable, such as a Python classes, this method will build up a stack of the nesting hierarchy so that it can be later de-nested correctly, inafter_content()
.For constructs that aren’t nestable, the stack is bypassed, and instead only the most recent object is tracked. This object prefix name will be removed with
after_content()
.- Return type:
None
- debug(message)
- directive_error(level, message)
Return a DirectiveError suitable for being thrown as an exception.
Call “raise self.directive_error(level, message)” from within a directive implementation to return one single system message at level level, which automatically gets the directive block and the line number added.
Preferably use the debug, info, warning, error, or severe wrapper methods, e.g.
self.error(message)
to generate an ERROR-level directive error.
- error(message)
- get_index_text(modname, name_cls)
Return the text for the index entry of the object.
- get_signature_prefix(sig)
Get the signature prefix for the directive.
- Parameters:
sig – The signature to process.
- Returns:
A list of nodes representing the signature prefix.
- Return type:
- get_signatures()
Retrieve the signatures to document from the directive arguments. By default, signatures are given as arguments, one per line.
- handle_signature(sig, signode)
Transform a Python signature into RST nodes.
Return (fully qualified name of the thing, classname if any).
If inside a class, the current class name is handled intelligently: * it is stripped from the displayed name if present * it is added to the full name (return value) if not present
- info(message)
- needs_arglist()
May return true if an empty argument list is to be generated even if the document contains none.
- Return type:
- parse_content_to_nodes(allow_section_headings=False)
Parse the directive’s content into nodes.
- Parameters:
allow_section_headings (bool) – Are titles (sections) allowed in the directive’s content? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of
Structural
nodes, which includesdocument
,section
, andsidebar
nodes.- Return type:
list[Node]
Added in version 7.4.
- parse_inline(text, *, lineno=-1)
Parse text as inline elements.
- Parameters:
- Returns:
A list of nodes (text and inline elements) and a list of system_messages.
- Return type:
Added in version 7.4.
- parse_text_to_nodes(text='', /, *, offset=-1, allow_section_headings=False)
Parse text into nodes.
- Parameters:
text (str) – Text, in string form.
StringList
is also accepted.allow_section_headings (bool) – Are titles (sections) allowed in text? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of
Structural
nodes, which includesdocument
,section
, andsidebar
nodes.offset (int) – The offset of the content.
- Return type:
list[Node]
Added in version 7.4.
- run()
Main directive entry function, called by docutils upon encountering the directive.
This directive is meant to be quite easily subclassable, so it delegates to several additional methods. What it does:
find out if called as a domain-specific directive, set self.domain
create a desc node to fit all description inside
parse standard options, currently no-index
create an index node if needed as self.indexnode
parse all given signatures (as returned by self.get_signatures()) using self.handle_signature(), which should either return a name or raise ValueError
add index entries using self.add_target_and_index()
parse the content and handle doc fields in it
- Return type:
list[Node]
- set_source_info(node)
Set source and line number to the node.
Added in version 2.1.
- Parameters:
node (Node)
- Return type:
None
- severe(message)
- transform_content(content_node)
Called after creating the content through nested parsing, but before the
object-description-transform
event is emitted, and before the info-fields are transformed. Can be used to manipulate the content.- Parameters:
content_node (desc_content)
- Return type:
None
- warning(message)
- allow_nesting = False
- property config: Config
Reference to the
Config
object.Added in version 1.8.
- doc_field_types: list[Field] = [<sphinx.domains.python._object.PyTypedField object>, <sphinx.domains.python._object.PyTypedField object>, <sphinx.domains.python._object.PyGroupedField object>, <sphinx.util.docfields.Field object>, <sphinx.domains.python._object.PyField object>, <sphinx.domains.python._object.PyTypedField object>]
- property env: BuildEnvironment
Reference to the
BuildEnvironment
object.Added in version 1.8.
- final_argument_whitespace = True
May the final argument contain whitespace?
- has_content = True
May the directive have content?
- indexnode: addnodes.index
- option_spec: ClassVar[OptionSpec] = {'annotation': <function unchanged>, 'async': <function flag>, 'canonical': <function unchanged>, 'module': <function unchanged>, 'no-contents-entry': <function flag>, 'no-index': <function flag>, 'no-index-entry': <function flag>, 'no-typesetting': <function flag>, 'nocontentsentry': <function flag>, 'noindex': <function flag>, 'noindexentry': <function flag>, 'single-line-parameter-list': <function flag>, 'single-line-type-parameter-list': <function flag>}
Mapping of option names to validator functions.
- optional_arguments = 0
Number of optional arguments after the required arguments.
- required_arguments = 1
Number of required directive arguments.
- class a_sync.sphinx.ext.ASyncFunctionDocumenter[source]
Bases:
_ASyncFunctionDocumenter
Document ASyncFunction instance definitions.
- typ
alias of
ASyncFunction
- __init__(directive, name, indent='')
- add_content(more_content)
Add content from docstrings, attribute documentation and user.
- Parameters:
more_content (StringList | None)
- Return type:
None
- add_directive_header(sig)
Add the directive header and options to the generated content.
- Parameters:
sig (str)
- Return type:
None
- add_line(line, source, *lineno)
Append one line of generated reST to the output.
- annotate_to_first_argument(func, typ)
Annotate type hint to the first argument of function if needed.
- Parameters:
func (Callable)
typ (type)
- Return type:
Callable | None
- classmethod can_document_member(member, membername, isattr, parent)
Determine if the member can be documented by this documenter.
- Parameters:
member – The member to check.
membername – The name of the member.
isattr – Boolean indicating if the member is an attribute.
parent – The parent object.
- Returns:
True if the member can be documented, False otherwise.
- Return type:
- check_module()
Check if the object is defined in the expected module.
- Returns:
True if the object is defined in the expected module, False otherwise.
- Return type:
Note
Normally checks if self.object is really defined in the module given by self.modname. But since functions decorated with the @task decorator are instances living in the celery.local, we have to check the wrapped function instead.
- document_members(all_members=False)
Document members of the object.
- Parameters:
all_members – Boolean indicating if all members should be documented.
- filter_members(members, want_all)
Filter the given member list.
Members are skipped if
they are private (except if given explicitly or the private-members option is set)
they are special methods (except if given explicitly or the special-members option is set)
they are undocumented (except if the undoc-members option is set)
The user can override the skipping decision by connecting to the
autodoc-skip-member
event.
- format_args()
Format the arguments of the wrapped function.
- Returns:
The formatted arguments.
- Return type:
- format_name()
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).
- Return type:
- format_signature(**kwargs)
Format the signature (arguments and return annotation) of the object.
Let the user process it via the
autodoc-process-signature
event.
- generate(more_content=None, real_modname=None, check_module=False, all_members=False)
Generate reST for the object given by self.name, and possibly for its members.
If more_content is given, include that content. If real_modname is given, use that module name to find attribute docs. If check_module is True, only generate if the object is defined in the module name it is imported from. If all_members is True, document all members.
- get_attr(obj, name, *defargs)
getattr() override for types such as Zope interfaces.
- get_doc()
Decode and return lines of the docstring(s) for the object.
When it returns None, autodoc-process-docstring will not be called for this object.
- get_object_members(want_all)
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).
- get_real_modname()
Get the real module name of an object to document.
It can differ from the name of the module through which the object was imported.
- Return type:
- import_object(raiseerror=False)
Import the object given by self.modname and self.objpath and set it as self.object.
Returns True if successful, False if an error occurred.
- merge_default_value(actual, overload)
Merge default values of actual implementation to the overload variants.
- parse_name()
Determine what module to import and what attribute to document.
Returns True and sets self.modname, self.objpath, self.fullname, self.args and self.retann if parsing and resolving was successful.
- Return type:
- process_doc(docstrings)
Let the user process the docstrings before adding them.
- resolve_name(modname, parents, path, base)
Resolve the module and name of the object to document given by the arguments and the current module/class.
Must return a pair of the module name and a chain of attributes; for example, it would return
('zipfile', ['ZipFile', 'open'])
for thezipfile.ZipFile.open
method.
- sort_members(documenters, order)
Sort the given member list.
- content_indent = ' '
indentation by which to indent the directive content
- member_order = 30
order if autodoc_member_order is set to ‘groupwise’
- objtype = 'a_sync_function'
name by which the directive is called (auto…) and the default generated directive name
- option_spec: ClassVar[OptionSpec] = {'no-index': <function bool_option>, 'noindex': <function bool_option>}
- priority = 15
priority if multiple documenters return True from can_document_member
- titles_allowed = True
true if the generated content may contain titles
- class a_sync.sphinx.ext.ASyncFunctionSyncDirective[source]
Bases:
_ASyncFunctionDirective
Directive for ASyncFunctionSyncDefault instances.
- __init__(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)
- _object_hierarchy_parts(sig_node)
Returns a tuple of strings, one entry for each part of the object’s hierarchy (e.g.
('module', 'submodule', 'Class', 'method')
). The returned tuple is used to properly nest children within parents in the table of contents, and can also be used within the_toc_entry_name()
method.This method must not be used outwith table of contents generation.
- _toc_entry_name(sig_node)
Returns the text of the table of contents entry for the object.
This function is called once, in
run()
, to set the name for the table of contents entry (a special attribute_toc_name
is set on the object node, later used inenvironment.collectors.toctree.TocTreeCollector.process_doc().build_toc()
when the table of contents entries are collected).To support table of contents entries for their objects, domains must override this method, also respecting the configuration setting
toc_object_entries_show_parents
. Domains must also override_object_hierarchy_parts()
, with one (string) entry for each part of the object’s hierarchy. The result of this method is set on the signature node, and can be accessed assig_node['_toc_parts']
for use within this method. The resulting tuple is also used to properly nest children within parents in the table of contents.An example implementations of this method is within the python domain (
PyObject._toc_entry_name()
). The python domain sets the_toc_parts
attribute within thehandle_signature()
method.- Parameters:
sig_node (desc_signature)
- Return type:
- add_name(node)
Append self.options[‘name’] to node[‘names’] if it exists.
Also normalize the name string and register it as explicit target.
- add_target_and_index(name_cls, sig, signode)
Add cross-reference IDs and entries to self.indexnode, if applicable.
name is whatever
handle_signature()
returned.
- after_content()
Handle object de-nesting after content
If this class is a nestable object, removing the last nested class prefix ends further nesting in the object.
If this class is not a nestable object, the list of classes should not be altered as we didn’t affect the nesting levels in
before_content()
.- Return type:
None
- assert_has_content()
Throw an ERROR-level DirectiveError if the directive doesn’t have contents.
- before_content()
Handle object nesting before content
PyObject
represents Python language constructs. For constructs that are nestable, such as a Python classes, this method will build up a stack of the nesting hierarchy so that it can be later de-nested correctly, inafter_content()
.For constructs that aren’t nestable, the stack is bypassed, and instead only the most recent object is tracked. This object prefix name will be removed with
after_content()
.- Return type:
None
- debug(message)
- directive_error(level, message)
Return a DirectiveError suitable for being thrown as an exception.
Call “raise self.directive_error(level, message)” from within a directive implementation to return one single system message at level level, which automatically gets the directive block and the line number added.
Preferably use the debug, info, warning, error, or severe wrapper methods, e.g.
self.error(message)
to generate an ERROR-level directive error.
- error(message)
- get_index_text(modname, name_cls)
Return the text for the index entry of the object.
- get_signature_prefix(sig)
Get the signature prefix for the directive.
- Parameters:
sig – The signature to process.
- Returns:
A list of nodes representing the signature prefix.
- Return type:
- get_signatures()
Retrieve the signatures to document from the directive arguments. By default, signatures are given as arguments, one per line.
- handle_signature(sig, signode)
Transform a Python signature into RST nodes.
Return (fully qualified name of the thing, classname if any).
If inside a class, the current class name is handled intelligently: * it is stripped from the displayed name if present * it is added to the full name (return value) if not present
- info(message)
- needs_arglist()
May return true if an empty argument list is to be generated even if the document contains none.
- Return type:
- parse_content_to_nodes(allow_section_headings=False)
Parse the directive’s content into nodes.
- Parameters:
allow_section_headings (bool) – Are titles (sections) allowed in the directive’s content? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of
Structural
nodes, which includesdocument
,section
, andsidebar
nodes.- Return type:
list[Node]
Added in version 7.4.
- parse_inline(text, *, lineno=-1)
Parse text as inline elements.
- Parameters:
- Returns:
A list of nodes (text and inline elements) and a list of system_messages.
- Return type:
Added in version 7.4.
- parse_text_to_nodes(text='', /, *, offset=-1, allow_section_headings=False)
Parse text into nodes.
- Parameters:
text (str) – Text, in string form.
StringList
is also accepted.allow_section_headings (bool) – Are titles (sections) allowed in text? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of
Structural
nodes, which includesdocument
,section
, andsidebar
nodes.offset (int) – The offset of the content.
- Return type:
list[Node]
Added in version 7.4.
- run()
Main directive entry function, called by docutils upon encountering the directive.
This directive is meant to be quite easily subclassable, so it delegates to several additional methods. What it does:
find out if called as a domain-specific directive, set self.domain
create a desc node to fit all description inside
parse standard options, currently no-index
create an index node if needed as self.indexnode
parse all given signatures (as returned by self.get_signatures()) using self.handle_signature(), which should either return a name or raise ValueError
add index entries using self.add_target_and_index()
parse the content and handle doc fields in it
- Return type:
list[Node]
- set_source_info(node)
Set source and line number to the node.
Added in version 2.1.
- Parameters:
node (Node)
- Return type:
None
- severe(message)
- transform_content(content_node)
Called after creating the content through nested parsing, but before the
object-description-transform
event is emitted, and before the info-fields are transformed. Can be used to manipulate the content.- Parameters:
content_node (desc_content)
- Return type:
None
- warning(message)
- allow_nesting = False
- property config: Config
Reference to the
Config
object.Added in version 1.8.
- doc_field_types: list[Field] = [<sphinx.domains.python._object.PyTypedField object>, <sphinx.domains.python._object.PyTypedField object>, <sphinx.domains.python._object.PyGroupedField object>, <sphinx.util.docfields.Field object>, <sphinx.domains.python._object.PyField object>, <sphinx.domains.python._object.PyTypedField object>]
- property env: BuildEnvironment
Reference to the
BuildEnvironment
object.Added in version 1.8.
- final_argument_whitespace = True
May the final argument contain whitespace?
- has_content = True
May the directive have content?
- indexnode: addnodes.index
- option_spec: ClassVar[OptionSpec] = {'annotation': <function unchanged>, 'async': <function flag>, 'canonical': <function unchanged>, 'module': <function unchanged>, 'no-contents-entry': <function flag>, 'no-index': <function flag>, 'no-index-entry': <function flag>, 'no-typesetting': <function flag>, 'nocontentsentry': <function flag>, 'noindex': <function flag>, 'noindexentry': <function flag>, 'single-line-parameter-list': <function flag>, 'single-line-type-parameter-list': <function flag>}
Mapping of option names to validator functions.
- optional_arguments = 0
Number of optional arguments after the required arguments.
- required_arguments = 1
Number of required directive arguments.
- class a_sync.sphinx.ext.ASyncFunctionSyncDocumenter[source]
Bases:
_ASyncFunctionDocumenter
Document ASyncFunctionSyncDefault instance definitions.
- typ
alias of
ASyncFunctionSyncDefault
- __init__(directive, name, indent='')
- add_content(more_content)
Add content from docstrings, attribute documentation and user.
- Parameters:
more_content (StringList | None)
- Return type:
None
- add_directive_header(sig)
Add the directive header and options to the generated content.
- Parameters:
sig (str)
- Return type:
None
- add_line(line, source, *lineno)
Append one line of generated reST to the output.
- annotate_to_first_argument(func, typ)
Annotate type hint to the first argument of function if needed.
- Parameters:
func (Callable)
typ (type)
- Return type:
Callable | None
- classmethod can_document_member(member, membername, isattr, parent)
Determine if the member can be documented by this documenter.
- Parameters:
member – The member to check.
membername – The name of the member.
isattr – Boolean indicating if the member is an attribute.
parent – The parent object.
- Returns:
True if the member can be documented, False otherwise.
- Return type:
- check_module()
Check if the object is defined in the expected module.
- Returns:
True if the object is defined in the expected module, False otherwise.
- Return type:
Note
Normally checks if self.object is really defined in the module given by self.modname. But since functions decorated with the @task decorator are instances living in the celery.local, we have to check the wrapped function instead.
- document_members(all_members=False)
Document members of the object.
- Parameters:
all_members – Boolean indicating if all members should be documented.
- filter_members(members, want_all)
Filter the given member list.
Members are skipped if
they are private (except if given explicitly or the private-members option is set)
they are special methods (except if given explicitly or the special-members option is set)
they are undocumented (except if the undoc-members option is set)
The user can override the skipping decision by connecting to the
autodoc-skip-member
event.
- format_args()
Format the arguments of the wrapped function.
- Returns:
The formatted arguments.
- Return type:
- format_name()
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).
- Return type:
- format_signature(**kwargs)
Format the signature (arguments and return annotation) of the object.
Let the user process it via the
autodoc-process-signature
event.
- generate(more_content=None, real_modname=None, check_module=False, all_members=False)
Generate reST for the object given by self.name, and possibly for its members.
If more_content is given, include that content. If real_modname is given, use that module name to find attribute docs. If check_module is True, only generate if the object is defined in the module name it is imported from. If all_members is True, document all members.
- get_attr(obj, name, *defargs)
getattr() override for types such as Zope interfaces.
- get_doc()
Decode and return lines of the docstring(s) for the object.
When it returns None, autodoc-process-docstring will not be called for this object.
- get_object_members(want_all)
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).
- get_real_modname()
Get the real module name of an object to document.
It can differ from the name of the module through which the object was imported.
- Return type:
- import_object(raiseerror=False)
Import the object given by self.modname and self.objpath and set it as self.object.
Returns True if successful, False if an error occurred.
- merge_default_value(actual, overload)
Merge default values of actual implementation to the overload variants.
- parse_name()
Determine what module to import and what attribute to document.
Returns True and sets self.modname, self.objpath, self.fullname, self.args and self.retann if parsing and resolving was successful.
- Return type:
- process_doc(docstrings)
Let the user process the docstrings before adding them.
- resolve_name(modname, parents, path, base)
Resolve the module and name of the object to document given by the arguments and the current module/class.
Must return a pair of the module name and a chain of attributes; for example, it would return
('zipfile', ['ZipFile', 'open'])
for thezipfile.ZipFile.open
method.
- sort_members(documenters, order)
Sort the given member list.
- content_indent = ' '
indentation by which to indent the directive content
- member_order = 30
order if autodoc_member_order is set to ‘groupwise’
- objtype = 'a_sync_function_sync'
name by which the directive is called (auto…) and the default generated directive name
- option_spec: ClassVar[OptionSpec] = {'no-index': <function bool_option>, 'noindex': <function bool_option>}
- priority = 14
priority if multiple documenters return True from can_document_member
- titles_allowed = True
true if the generated content may contain titles
- class a_sync.sphinx.ext.ASyncGeneratorFunctionDirective[source]
Bases:
_ASyncFunctionDirective
Directive for ASyncGeneratorFunction instances.
- __init__(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)
- _object_hierarchy_parts(sig_node)
Returns a tuple of strings, one entry for each part of the object’s hierarchy (e.g.
('module', 'submodule', 'Class', 'method')
). The returned tuple is used to properly nest children within parents in the table of contents, and can also be used within the_toc_entry_name()
method.This method must not be used outwith table of contents generation.
- _toc_entry_name(sig_node)
Returns the text of the table of contents entry for the object.
This function is called once, in
run()
, to set the name for the table of contents entry (a special attribute_toc_name
is set on the object node, later used inenvironment.collectors.toctree.TocTreeCollector.process_doc().build_toc()
when the table of contents entries are collected).To support table of contents entries for their objects, domains must override this method, also respecting the configuration setting
toc_object_entries_show_parents
. Domains must also override_object_hierarchy_parts()
, with one (string) entry for each part of the object’s hierarchy. The result of this method is set on the signature node, and can be accessed assig_node['_toc_parts']
for use within this method. The resulting tuple is also used to properly nest children within parents in the table of contents.An example implementations of this method is within the python domain (
PyObject._toc_entry_name()
). The python domain sets the_toc_parts
attribute within thehandle_signature()
method.- Parameters:
sig_node (desc_signature)
- Return type:
- add_name(node)
Append self.options[‘name’] to node[‘names’] if it exists.
Also normalize the name string and register it as explicit target.
- add_target_and_index(name_cls, sig, signode)
Add cross-reference IDs and entries to self.indexnode, if applicable.
name is whatever
handle_signature()
returned.
- after_content()
Handle object de-nesting after content
If this class is a nestable object, removing the last nested class prefix ends further nesting in the object.
If this class is not a nestable object, the list of classes should not be altered as we didn’t affect the nesting levels in
before_content()
.- Return type:
None
- assert_has_content()
Throw an ERROR-level DirectiveError if the directive doesn’t have contents.
- before_content()
Handle object nesting before content
PyObject
represents Python language constructs. For constructs that are nestable, such as a Python classes, this method will build up a stack of the nesting hierarchy so that it can be later de-nested correctly, inafter_content()
.For constructs that aren’t nestable, the stack is bypassed, and instead only the most recent object is tracked. This object prefix name will be removed with
after_content()
.- Return type:
None
- debug(message)
- directive_error(level, message)
Return a DirectiveError suitable for being thrown as an exception.
Call “raise self.directive_error(level, message)” from within a directive implementation to return one single system message at level level, which automatically gets the directive block and the line number added.
Preferably use the debug, info, warning, error, or severe wrapper methods, e.g.
self.error(message)
to generate an ERROR-level directive error.
- error(message)
- get_index_text(modname, name_cls)
Return the text for the index entry of the object.
- get_signature_prefix(sig)
Get the signature prefix for the directive.
- Parameters:
sig – The signature to process.
- Returns:
A list of nodes representing the signature prefix.
- Return type:
- get_signatures()
Retrieve the signatures to document from the directive arguments. By default, signatures are given as arguments, one per line.
- handle_signature(sig, signode)
Transform a Python signature into RST nodes.
Return (fully qualified name of the thing, classname if any).
If inside a class, the current class name is handled intelligently: * it is stripped from the displayed name if present * it is added to the full name (return value) if not present
- info(message)
- needs_arglist()
May return true if an empty argument list is to be generated even if the document contains none.
- Return type:
- parse_content_to_nodes(allow_section_headings=False)
Parse the directive’s content into nodes.
- Parameters:
allow_section_headings (bool) – Are titles (sections) allowed in the directive’s content? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of
Structural
nodes, which includesdocument
,section
, andsidebar
nodes.- Return type:
list[Node]
Added in version 7.4.
- parse_inline(text, *, lineno=-1)
Parse text as inline elements.
- Parameters:
- Returns:
A list of nodes (text and inline elements) and a list of system_messages.
- Return type:
Added in version 7.4.
- parse_text_to_nodes(text='', /, *, offset=-1, allow_section_headings=False)
Parse text into nodes.
- Parameters:
text (str) – Text, in string form.
StringList
is also accepted.allow_section_headings (bool) – Are titles (sections) allowed in text? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of
Structural
nodes, which includesdocument
,section
, andsidebar
nodes.offset (int) – The offset of the content.
- Return type:
list[Node]
Added in version 7.4.
- run()
Main directive entry function, called by docutils upon encountering the directive.
This directive is meant to be quite easily subclassable, so it delegates to several additional methods. What it does:
find out if called as a domain-specific directive, set self.domain
create a desc node to fit all description inside
parse standard options, currently no-index
create an index node if needed as self.indexnode
parse all given signatures (as returned by self.get_signatures()) using self.handle_signature(), which should either return a name or raise ValueError
add index entries using self.add_target_and_index()
parse the content and handle doc fields in it
- Return type:
list[Node]
- set_source_info(node)
Set source and line number to the node.
Added in version 2.1.
- Parameters:
node (Node)
- Return type:
None
- severe(message)
- transform_content(content_node)
Called after creating the content through nested parsing, but before the
object-description-transform
event is emitted, and before the info-fields are transformed. Can be used to manipulate the content.- Parameters:
content_node (desc_content)
- Return type:
None
- warning(message)
- allow_nesting = False
- property config: Config
Reference to the
Config
object.Added in version 1.8.
- doc_field_types: list[Field] = [<sphinx.domains.python._object.PyTypedField object>, <sphinx.domains.python._object.PyTypedField object>, <sphinx.domains.python._object.PyGroupedField object>, <sphinx.util.docfields.Field object>, <sphinx.domains.python._object.PyField object>, <sphinx.domains.python._object.PyTypedField object>]
- property env: BuildEnvironment
Reference to the
BuildEnvironment
object.Added in version 1.8.
- final_argument_whitespace = True
May the final argument contain whitespace?
- has_content = True
May the directive have content?
- indexnode: addnodes.index
- option_spec: ClassVar[OptionSpec] = {'annotation': <function unchanged>, 'async': <function flag>, 'canonical': <function unchanged>, 'module': <function unchanged>, 'no-contents-entry': <function flag>, 'no-index': <function flag>, 'no-index-entry': <function flag>, 'no-typesetting': <function flag>, 'nocontentsentry': <function flag>, 'noindex': <function flag>, 'noindexentry': <function flag>, 'single-line-parameter-list': <function flag>, 'single-line-type-parameter-list': <function flag>}
Mapping of option names to validator functions.
- optional_arguments = 0
Number of optional arguments after the required arguments.
- required_arguments = 1
Number of required directive arguments.
- class a_sync.sphinx.ext.ASyncGeneratorFunctionDocumenter[source]
Bases:
_ASyncFunctionDocumenter
Document ASyncGeneratorFunction instance definitions.
- typ
alias of
ASyncGeneratorFunction
- __init__(directive, name, indent='')
- add_content(more_content)
Add content from docstrings, attribute documentation and user.
- Parameters:
more_content (StringList | None)
- Return type:
None
- add_directive_header(sig)
Add the directive header and options to the generated content.
- Parameters:
sig (str)
- Return type:
None
- add_line(line, source, *lineno)
Append one line of generated reST to the output.
- annotate_to_first_argument(func, typ)
Annotate type hint to the first argument of function if needed.
- Parameters:
func (Callable)
typ (type)
- Return type:
Callable | None
- classmethod can_document_member(member, membername, isattr, parent)
Determine if the member can be documented by this documenter.
- Parameters:
member – The member to check.
membername – The name of the member.
isattr – Boolean indicating if the member is an attribute.
parent – The parent object.
- Returns:
True if the member can be documented, False otherwise.
- Return type:
- check_module()
Check if the object is defined in the expected module.
- Returns:
True if the object is defined in the expected module, False otherwise.
- Return type:
Note
Normally checks if self.object is really defined in the module given by self.modname. But since functions decorated with the @task decorator are instances living in the celery.local, we have to check the wrapped function instead.
- document_members(all_members=False)
Document members of the object.
- Parameters:
all_members – Boolean indicating if all members should be documented.
- filter_members(members, want_all)
Filter the given member list.
Members are skipped if
they are private (except if given explicitly or the private-members option is set)
they are special methods (except if given explicitly or the special-members option is set)
they are undocumented (except if the undoc-members option is set)
The user can override the skipping decision by connecting to the
autodoc-skip-member
event.
- format_args()
Format the arguments of the wrapped function.
- Returns:
The formatted arguments.
- Return type:
- format_name()
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).
- Return type:
- format_signature(**kwargs)
Format the signature (arguments and return annotation) of the object.
Let the user process it via the
autodoc-process-signature
event.
- generate(more_content=None, real_modname=None, check_module=False, all_members=False)
Generate reST for the object given by self.name, and possibly for its members.
If more_content is given, include that content. If real_modname is given, use that module name to find attribute docs. If check_module is True, only generate if the object is defined in the module name it is imported from. If all_members is True, document all members.
- get_attr(obj, name, *defargs)
getattr() override for types such as Zope interfaces.
- get_doc()
Decode and return lines of the docstring(s) for the object.
When it returns None, autodoc-process-docstring will not be called for this object.
- get_object_members(want_all)
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).
- get_real_modname()
Get the real module name of an object to document.
It can differ from the name of the module through which the object was imported.
- Return type:
- import_object(raiseerror=False)
Import the object given by self.modname and self.objpath and set it as self.object.
Returns True if successful, False if an error occurred.
- merge_default_value(actual, overload)
Merge default values of actual implementation to the overload variants.
- parse_name()
Determine what module to import and what attribute to document.
Returns True and sets self.modname, self.objpath, self.fullname, self.args and self.retann if parsing and resolving was successful.
- Return type:
- process_doc(docstrings)
Let the user process the docstrings before adding them.
- resolve_name(modname, parents, path, base)
Resolve the module and name of the object to document given by the arguments and the current module/class.
Must return a pair of the module name and a chain of attributes; for example, it would return
('zipfile', ['ZipFile', 'open'])
for thezipfile.ZipFile.open
method.
- sort_members(documenters, order)
Sort the given member list.
- content_indent = ' '
indentation by which to indent the directive content
- member_order = 30
order if autodoc_member_order is set to ‘groupwise’
- objtype = 'a_sync_generator_function'
name by which the directive is called (auto…) and the default generated directive name
- option_spec: ClassVar[OptionSpec] = {'no-index': <function bool_option>, 'noindex': <function bool_option>}
- priority = 0
priority if multiple documenters return True from can_document_member
- titles_allowed = True
true if the generated content may contain titles
- class a_sync.sphinx.ext._ASyncDirective[source]
Bases:
object
Base class for ASync directives.
- class a_sync.sphinx.ext._ASyncFunctionDirective[source]
Bases:
_ASyncDirective
,PyFunction
Directive for ASyncFunction instances.
- __init__(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)
- _object_hierarchy_parts(sig_node)
Returns a tuple of strings, one entry for each part of the object’s hierarchy (e.g.
('module', 'submodule', 'Class', 'method')
). The returned tuple is used to properly nest children within parents in the table of contents, and can also be used within the_toc_entry_name()
method.This method must not be used outwith table of contents generation.
- _toc_entry_name(sig_node)
Returns the text of the table of contents entry for the object.
This function is called once, in
run()
, to set the name for the table of contents entry (a special attribute_toc_name
is set on the object node, later used inenvironment.collectors.toctree.TocTreeCollector.process_doc().build_toc()
when the table of contents entries are collected).To support table of contents entries for their objects, domains must override this method, also respecting the configuration setting
toc_object_entries_show_parents
. Domains must also override_object_hierarchy_parts()
, with one (string) entry for each part of the object’s hierarchy. The result of this method is set on the signature node, and can be accessed assig_node['_toc_parts']
for use within this method. The resulting tuple is also used to properly nest children within parents in the table of contents.An example implementations of this method is within the python domain (
PyObject._toc_entry_name()
). The python domain sets the_toc_parts
attribute within thehandle_signature()
method.- Parameters:
sig_node (desc_signature)
- Return type:
- add_name(node)
Append self.options[‘name’] to node[‘names’] if it exists.
Also normalize the name string and register it as explicit target.
- add_target_and_index(name_cls, sig, signode)
Add cross-reference IDs and entries to self.indexnode, if applicable.
name is whatever
handle_signature()
returned.
- after_content()
Handle object de-nesting after content
If this class is a nestable object, removing the last nested class prefix ends further nesting in the object.
If this class is not a nestable object, the list of classes should not be altered as we didn’t affect the nesting levels in
before_content()
.- Return type:
None
- assert_has_content()
Throw an ERROR-level DirectiveError if the directive doesn’t have contents.
- before_content()
Handle object nesting before content
PyObject
represents Python language constructs. For constructs that are nestable, such as a Python classes, this method will build up a stack of the nesting hierarchy so that it can be later de-nested correctly, inafter_content()
.For constructs that aren’t nestable, the stack is bypassed, and instead only the most recent object is tracked. This object prefix name will be removed with
after_content()
.- Return type:
None
- debug(message)
- directive_error(level, message)
Return a DirectiveError suitable for being thrown as an exception.
Call “raise self.directive_error(level, message)” from within a directive implementation to return one single system message at level level, which automatically gets the directive block and the line number added.
Preferably use the debug, info, warning, error, or severe wrapper methods, e.g.
self.error(message)
to generate an ERROR-level directive error.
- error(message)
- get_index_text(modname, name_cls)
Return the text for the index entry of the object.
- get_signature_prefix(sig)
Get the signature prefix for the directive.
- Parameters:
sig – The signature to process.
- Returns:
A list of nodes representing the signature prefix.
- Return type:
- get_signatures()
Retrieve the signatures to document from the directive arguments. By default, signatures are given as arguments, one per line.
- handle_signature(sig, signode)
Transform a Python signature into RST nodes.
Return (fully qualified name of the thing, classname if any).
If inside a class, the current class name is handled intelligently: * it is stripped from the displayed name if present * it is added to the full name (return value) if not present
- info(message)
- needs_arglist()
May return true if an empty argument list is to be generated even if the document contains none.
- Return type:
- parse_content_to_nodes(allow_section_headings=False)
Parse the directive’s content into nodes.
- Parameters:
allow_section_headings (bool) – Are titles (sections) allowed in the directive’s content? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of
Structural
nodes, which includesdocument
,section
, andsidebar
nodes.- Return type:
list[Node]
Added in version 7.4.
- parse_inline(text, *, lineno=-1)
Parse text as inline elements.
- Parameters:
- Returns:
A list of nodes (text and inline elements) and a list of system_messages.
- Return type:
Added in version 7.4.
- parse_text_to_nodes(text='', /, *, offset=-1, allow_section_headings=False)
Parse text into nodes.
- Parameters:
text (str) – Text, in string form.
StringList
is also accepted.allow_section_headings (bool) – Are titles (sections) allowed in text? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of
Structural
nodes, which includesdocument
,section
, andsidebar
nodes.offset (int) – The offset of the content.
- Return type:
list[Node]
Added in version 7.4.
- run()
Main directive entry function, called by docutils upon encountering the directive.
This directive is meant to be quite easily subclassable, so it delegates to several additional methods. What it does:
find out if called as a domain-specific directive, set self.domain
create a desc node to fit all description inside
parse standard options, currently no-index
create an index node if needed as self.indexnode
parse all given signatures (as returned by self.get_signatures()) using self.handle_signature(), which should either return a name or raise ValueError
add index entries using self.add_target_and_index()
parse the content and handle doc fields in it
- Return type:
list[Node]
- set_source_info(node)
Set source and line number to the node.
Added in version 2.1.
- Parameters:
node (Node)
- Return type:
None
- severe(message)
- transform_content(content_node)
Called after creating the content through nested parsing, but before the
object-description-transform
event is emitted, and before the info-fields are transformed. Can be used to manipulate the content.- Parameters:
content_node (desc_content)
- Return type:
None
- warning(message)
- allow_nesting = False
- property config: Config
Reference to the
Config
object.Added in version 1.8.
- doc_field_types: list[Field] = [<sphinx.domains.python._object.PyTypedField object>, <sphinx.domains.python._object.PyTypedField object>, <sphinx.domains.python._object.PyGroupedField object>, <sphinx.util.docfields.Field object>, <sphinx.domains.python._object.PyField object>, <sphinx.domains.python._object.PyTypedField object>]
- property env: BuildEnvironment
Reference to the
BuildEnvironment
object.Added in version 1.8.
- final_argument_whitespace = True
May the final argument contain whitespace?
- has_content = True
May the directive have content?
- indexnode: addnodes.index
- option_spec: ClassVar[OptionSpec] = {'annotation': <function unchanged>, 'async': <function flag>, 'canonical': <function unchanged>, 'module': <function unchanged>, 'no-contents-entry': <function flag>, 'no-index': <function flag>, 'no-index-entry': <function flag>, 'no-typesetting': <function flag>, 'nocontentsentry': <function flag>, 'noindex': <function flag>, 'noindexentry': <function flag>, 'single-line-parameter-list': <function flag>, 'single-line-type-parameter-list': <function flag>}
Mapping of option names to validator functions.
- optional_arguments = 0
Number of optional arguments after the required arguments.
- required_arguments = 1
Number of required directive arguments.
- class a_sync.sphinx.ext._ASyncFunctionDocumenter[source]
Bases:
_ASyncWrapperDocumenter
,FunctionDocumenter
Documenter for ASyncFunction instances.
- __init__(directive, name, indent='')
- add_content(more_content)
Add content from docstrings, attribute documentation and user.
- Parameters:
more_content (StringList | None)
- Return type:
None
- add_directive_header(sig)
Add the directive header and options to the generated content.
- Parameters:
sig (str)
- Return type:
None
- add_line(line, source, *lineno)
Append one line of generated reST to the output.
- annotate_to_first_argument(func, typ)
Annotate type hint to the first argument of function if needed.
- Parameters:
func (Callable)
typ (type)
- Return type:
Callable | None
- classmethod can_document_member(member, membername, isattr, parent)
Determine if the member can be documented by this documenter.
- Parameters:
member – The member to check.
membername – The name of the member.
isattr – Boolean indicating if the member is an attribute.
parent – The parent object.
- Returns:
True if the member can be documented, False otherwise.
- Return type:
- check_module()
Check if the object is defined in the expected module.
- Returns:
True if the object is defined in the expected module, False otherwise.
- Return type:
Note
Normally checks if self.object is really defined in the module given by self.modname. But since functions decorated with the @task decorator are instances living in the celery.local, we have to check the wrapped function instead.
- document_members(all_members=False)
Document members of the object.
- Parameters:
all_members – Boolean indicating if all members should be documented.
- filter_members(members, want_all)
Filter the given member list.
Members are skipped if
they are private (except if given explicitly or the private-members option is set)
they are special methods (except if given explicitly or the special-members option is set)
they are undocumented (except if the undoc-members option is set)
The user can override the skipping decision by connecting to the
autodoc-skip-member
event.
- format_args()[source]
Format the arguments of the wrapped function.
- Returns:
The formatted arguments.
- Return type:
- format_name()
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).
- Return type:
- format_signature(**kwargs)
Format the signature (arguments and return annotation) of the object.
Let the user process it via the
autodoc-process-signature
event.
- generate(more_content=None, real_modname=None, check_module=False, all_members=False)
Generate reST for the object given by self.name, and possibly for its members.
If more_content is given, include that content. If real_modname is given, use that module name to find attribute docs. If check_module is True, only generate if the object is defined in the module name it is imported from. If all_members is True, document all members.
- get_attr(obj, name, *defargs)
getattr() override for types such as Zope interfaces.
- get_doc()
Decode and return lines of the docstring(s) for the object.
When it returns None, autodoc-process-docstring will not be called for this object.
- get_object_members(want_all)
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).
- get_real_modname()
Get the real module name of an object to document.
It can differ from the name of the module through which the object was imported.
- Return type:
- import_object(raiseerror=False)
Import the object given by self.modname and self.objpath and set it as self.object.
Returns True if successful, False if an error occurred.
- merge_default_value(actual, overload)
Merge default values of actual implementation to the overload variants.
- parse_name()
Determine what module to import and what attribute to document.
Returns True and sets self.modname, self.objpath, self.fullname, self.args and self.retann if parsing and resolving was successful.
- Return type:
- process_doc(docstrings)
Let the user process the docstrings before adding them.
- resolve_name(modname, parents, path, base)
Resolve the module and name of the object to document given by the arguments and the current module/class.
Must return a pair of the module name and a chain of attributes; for example, it would return
('zipfile', ['ZipFile', 'open'])
for thezipfile.ZipFile.open
method.
- sort_members(documenters, order)
Sort the given member list.
- content_indent = ' '
indentation by which to indent the directive content
- member_order = 30
order if autodoc_member_order is set to ‘groupwise’
- objtype = 'function'
name by which the directive is called (auto…) and the default generated directive name
- option_spec: ClassVar[OptionSpec] = {'no-index': <function bool_option>, 'noindex': <function bool_option>}
- priority = 0
priority if multiple documenters return True from can_document_member
- titles_allowed = True
true if the generated content may contain titles
- class a_sync.sphinx.ext._ASyncMethodDirective[source]
Bases:
_ASyncDirective
,PyMethod
Directive for ASyncMethod instances.
- __init__(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)
- _object_hierarchy_parts(sig_node)
Returns a tuple of strings, one entry for each part of the object’s hierarchy (e.g.
('module', 'submodule', 'Class', 'method')
). The returned tuple is used to properly nest children within parents in the table of contents, and can also be used within the_toc_entry_name()
method.This method must not be used outwith table of contents generation.
- _toc_entry_name(sig_node)
Returns the text of the table of contents entry for the object.
This function is called once, in
run()
, to set the name for the table of contents entry (a special attribute_toc_name
is set on the object node, later used inenvironment.collectors.toctree.TocTreeCollector.process_doc().build_toc()
when the table of contents entries are collected).To support table of contents entries for their objects, domains must override this method, also respecting the configuration setting
toc_object_entries_show_parents
. Domains must also override_object_hierarchy_parts()
, with one (string) entry for each part of the object’s hierarchy. The result of this method is set on the signature node, and can be accessed assig_node['_toc_parts']
for use within this method. The resulting tuple is also used to properly nest children within parents in the table of contents.An example implementations of this method is within the python domain (
PyObject._toc_entry_name()
). The python domain sets the_toc_parts
attribute within thehandle_signature()
method.- Parameters:
sig_node (desc_signature)
- Return type:
- add_name(node)
Append self.options[‘name’] to node[‘names’] if it exists.
Also normalize the name string and register it as explicit target.
- add_target_and_index(name_cls, sig, signode)
Add cross-reference IDs and entries to self.indexnode, if applicable.
name is whatever
handle_signature()
returned.
- after_content()
Handle object de-nesting after content
If this class is a nestable object, removing the last nested class prefix ends further nesting in the object.
If this class is not a nestable object, the list of classes should not be altered as we didn’t affect the nesting levels in
before_content()
.- Return type:
None
- assert_has_content()
Throw an ERROR-level DirectiveError if the directive doesn’t have contents.
- before_content()
Handle object nesting before content
PyObject
represents Python language constructs. For constructs that are nestable, such as a Python classes, this method will build up a stack of the nesting hierarchy so that it can be later de-nested correctly, inafter_content()
.For constructs that aren’t nestable, the stack is bypassed, and instead only the most recent object is tracked. This object prefix name will be removed with
after_content()
.- Return type:
None
- debug(message)
- directive_error(level, message)
Return a DirectiveError suitable for being thrown as an exception.
Call “raise self.directive_error(level, message)” from within a directive implementation to return one single system message at level level, which automatically gets the directive block and the line number added.
Preferably use the debug, info, warning, error, or severe wrapper methods, e.g.
self.error(message)
to generate an ERROR-level directive error.
- error(message)
- get_index_text(modname, name_cls)
Return the text for the index entry of the object.
- get_signature_prefix(sig)
Get the signature prefix for the directive.
- Parameters:
sig – The signature to process.
- Returns:
A list of nodes representing the signature prefix.
- Return type:
- get_signatures()
Retrieve the signatures to document from the directive arguments. By default, signatures are given as arguments, one per line.
- handle_signature(sig, signode)
Transform a Python signature into RST nodes.
Return (fully qualified name of the thing, classname if any).
If inside a class, the current class name is handled intelligently: * it is stripped from the displayed name if present * it is added to the full name (return value) if not present
- info(message)
- needs_arglist()
May return true if an empty argument list is to be generated even if the document contains none.
- Return type:
- parse_content_to_nodes(allow_section_headings=False)
Parse the directive’s content into nodes.
- Parameters:
allow_section_headings (bool) – Are titles (sections) allowed in the directive’s content? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of
Structural
nodes, which includesdocument
,section
, andsidebar
nodes.- Return type:
list[Node]
Added in version 7.4.
- parse_inline(text, *, lineno=-1)
Parse text as inline elements.
- Parameters:
- Returns:
A list of nodes (text and inline elements) and a list of system_messages.
- Return type:
Added in version 7.4.
- parse_text_to_nodes(text='', /, *, offset=-1, allow_section_headings=False)
Parse text into nodes.
- Parameters:
text (str) – Text, in string form.
StringList
is also accepted.allow_section_headings (bool) – Are titles (sections) allowed in text? Note that this option bypasses Docutils’ usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of
Structural
nodes, which includesdocument
,section
, andsidebar
nodes.offset (int) – The offset of the content.
- Return type:
list[Node]
Added in version 7.4.
- run()
Main directive entry function, called by docutils upon encountering the directive.
This directive is meant to be quite easily subclassable, so it delegates to several additional methods. What it does:
find out if called as a domain-specific directive, set self.domain
create a desc node to fit all description inside
parse standard options, currently no-index
create an index node if needed as self.indexnode
parse all given signatures (as returned by self.get_signatures()) using self.handle_signature(), which should either return a name or raise ValueError
add index entries using self.add_target_and_index()
parse the content and handle doc fields in it
- Return type:
list[Node]
- set_source_info(node)
Set source and line number to the node.
Added in version 2.1.
- Parameters:
node (Node)
- Return type:
None
- severe(message)
- transform_content(content_node)
Called after creating the content through nested parsing, but before the
object-description-transform
event is emitted, and before the info-fields are transformed. Can be used to manipulate the content.- Parameters:
content_node (desc_content)
- Return type:
None
- warning(message)
- allow_nesting = False
- property config: Config
Reference to the
Config
object.Added in version 1.8.
- doc_field_types: list[Field] = [<sphinx.domains.python._object.PyTypedField object>, <sphinx.domains.python._object.PyTypedField object>, <sphinx.domains.python._object.PyGroupedField object>, <sphinx.util.docfields.Field object>, <sphinx.domains.python._object.PyField object>, <sphinx.domains.python._object.PyTypedField object>]
- property env: BuildEnvironment
Reference to the
BuildEnvironment
object.Added in version 1.8.
- final_argument_whitespace = True
May the final argument contain whitespace?
- has_content = True
May the directive have content?
- indexnode: addnodes.index
- option_spec: ClassVar[OptionSpec] = {'abstractmethod': <function flag>, 'annotation': <function unchanged>, 'async': <function flag>, 'canonical': <function unchanged>, 'classmethod': <function flag>, 'final': <function flag>, 'module': <function unchanged>, 'no-contents-entry': <function flag>, 'no-index': <function flag>, 'no-index-entry': <function flag>, 'no-typesetting': <function flag>, 'nocontentsentry': <function flag>, 'noindex': <function flag>, 'noindexentry': <function flag>, 'single-line-parameter-list': <function flag>, 'single-line-type-parameter-list': <function flag>, 'staticmethod': <function flag>}
Mapping of option names to validator functions.
- optional_arguments = 0
Number of optional arguments after the required arguments.
- required_arguments = 1
Number of required directive arguments.
- class a_sync.sphinx.ext._ASyncMethodDocumenter[source]
Bases:
_ASyncWrapperDocumenter
,MethodDocumenter
Documenter for ASyncMethod instances.
- __init__(directive, name, indent='')
- add_content(more_content)
Add content from docstrings, attribute documentation and user.
- Parameters:
more_content (StringList | None)
- Return type:
None
- add_directive_header(sig)
Add the directive header and options to the generated content.
- Parameters:
sig (str)
- Return type:
None
- add_line(line, source, *lineno)
Append one line of generated reST to the output.
- annotate_to_first_argument(func, typ)
Annotate type hint to the first argument of function if needed.
- Parameters:
func (Callable)
typ (type)
- Return type:
Callable | None
- classmethod can_document_member(member, membername, isattr, parent)
Determine if the member can be documented by this documenter.
- Parameters:
member – The member to check.
membername – The name of the member.
isattr – Boolean indicating if the member is an attribute.
parent – The parent object.
- Returns:
True if the member can be documented, False otherwise.
- Return type:
- check_module()
Check if the object is defined in the expected module.
- Returns:
True if the object is defined in the expected module, False otherwise.
- Return type:
Note
Normally checks if self.object is really defined in the module given by self.modname. But since functions decorated with the @task decorator are instances living in the celery.local, we have to check the wrapped function instead.
- document_members(all_members=False)
Document members of the object.
- Parameters:
all_members – Boolean indicating if all members should be documented.
- filter_members(members, want_all)
Filter the given member list.
Members are skipped if
they are private (except if given explicitly or the private-members option is set)
they are special methods (except if given explicitly or the special-members option is set)
they are undocumented (except if the undoc-members option is set)
The user can override the skipping decision by connecting to the
autodoc-skip-member
event.
- format_args()[source]
Format the arguments of the wrapped method.
- Returns:
The formatted arguments.
- Return type:
- format_name()
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).
- Return type:
- format_signature(**kwargs)
Format the signature (arguments and return annotation) of the object.
Let the user process it via the
autodoc-process-signature
event.
- generate(more_content=None, real_modname=None, check_module=False, all_members=False)
Generate reST for the object given by self.name, and possibly for its members.
If more_content is given, include that content. If real_modname is given, use that module name to find attribute docs. If check_module is True, only generate if the object is defined in the module name it is imported from. If all_members is True, document all members.
- get_attr(obj, name, *defargs)
getattr() override for types such as Zope interfaces.
- get_doc()
Decode and return lines of the docstring(s) for the object.
When it returns None, autodoc-process-docstring will not be called for this object.
- get_object_members(want_all)
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).
- get_real_modname()
Get the real module name of an object to document.
It can differ from the name of the module through which the object was imported.
- Return type:
- import_object(raiseerror=False)
Import the object given by self.modname and self.objpath and set it as self.object.
Returns True if successful, False if an error occurred.
- merge_default_value(actual, overload)
Merge default values of actual implementation to the overload variants.
- parse_name()
Determine what module to import and what attribute to document.
Returns True and sets self.modname, self.objpath, self.fullname, self.args and self.retann if parsing and resolving was successful.
- Return type:
- process_doc(docstrings)
Let the user process the docstrings before adding them.
- resolve_name(modname, parents, path, base)
Resolve the module and name of the object to document given by the arguments and the current module/class.
Must return a pair of the module name and a chain of attributes; for example, it would return
('zipfile', ['ZipFile', 'open'])
for thezipfile.ZipFile.open
method.
- sort_members(documenters, order)
Sort the given member list.
- content_indent = ' '
indentation by which to indent the directive content
- directivetype = 'method'
- member_order = 50
order if autodoc_member_order is set to ‘groupwise’
- objtype = 'method'
name by which the directive is called (auto…) and the default generated directive name
- option_spec: ClassVar[OptionSpec] = {'no-index': <function bool_option>, 'noindex': <function bool_option>}
- priority = 1
priority if multiple documenters return True from can_document_member
- titles_allowed = True
true if the generated content may contain titles
- class a_sync.sphinx.ext._ASyncWrapperDocumenter[source]
Bases:
object
Base class for documenters that handle wrapped ASync functions.
- classmethod can_document_member(member, membername, isattr, parent)[source]
Determine if the member can be documented by this documenter.
- Parameters:
member – The member to check.
membername – The name of the member.
isattr – Boolean indicating if the member is an attribute.
parent – The parent object.
- Returns:
True if the member can be documented, False otherwise.
- Return type:
- check_module()[source]
Check if the object is defined in the expected module.
- Returns:
True if the object is defined in the expected module, False otherwise.
- Return type:
Note
Normally checks if self.object is really defined in the module given by self.modname. But since functions decorated with the @task decorator are instances living in the celery.local, we have to check the wrapped function instead.
- a_sync.sphinx.ext.autodoc_skip_member_handler(app, what, name, obj, skip, options)[source]
Handler for autodoc-skip-member event.
- Parameters:
app – The Sphinx application object.
what – The type of the object being documented.
name – The name of the object.
obj – The object itself.
skip – Boolean indicating if the member should be skipped.
options – The options for the autodoc directive.
- Returns:
True if the member should be skipped, False otherwise.
- Return type: