Sage autodoc extension

This is sphinx.ext.autodoc extension modified for Sage objects.

The original header of sphinx.ext.autodoc:

Extension to create automatic documentation from code docstrings.

Automatically insert docstrings for functions, classes or whole modules into the doctree, thus avoiding duplication between docstrings and documentation for those who like elaborate docstrings.

This module is currently based on sphinx.ext.autodoc from Sphinx version 8.0.2. Compare (do diff) with the upstream source file sphinx/ext/autodoc/__init__.py.

In the source file of this module, major modifications are delimited by a pair of comment dividers. To lessen maintenance burden, we aim at reducing the modifications.

AUTHORS:

• ? (before 2011): initial version derived from sphinx.ext.autodoc

• Johan S. R. Nielsen: support for _sage_argspec_

• Simon King (2011-04): use sageinspect; include public cython attributes only in the documentation if they have a docstring

• Kwankyu Lee (2018-12-26, 2022-11-08): rebased on the latest sphinx.ext.autodoc

• Kwankyu Lee (2024-02-14): rebased on Sphinx 7.2.6

• François Bissey (2024-08-24): rebased on Sphinx 8.0.2

• François Bissey (2024-09-10): Tweaks to support python 3.9 (and older sphinx) as well

• François Bissey (2024-11-12): rebased on Sphinx 8.1.3 (while trying to keep python 3.9 compatibility)

class sage_docbuild.ext.sage_autodoc.AttributeDocumenter(directive: DocumenterBridge, name: str, indent: str = '')

Bases: GenericAliasMixin, SlotsMixin, RuntimeInstanceAttributeMixin, UninitializedInstanceAttributeMixin, NonDataDescriptorMixin, DocstringStripSignatureMixin, ClassLevelDocumenter

Specialized Documenter subclass for attributes.

add_content(more_content)

add_directive_header(sig)

classmethod can_document_member(member, membername, isattr, parent)

document_members(all_members=False)

get_attribute_comment(parent, attrname)

get_doc()

get_real_modname()

import_object(raiseerror=False)

static is_function_or_method(obj)

member_order = 60

order if autodoc_member_order is set to ‘groupwise’

objtype = 'attribute'

name by which the directive is called (auto…) and the default generated directive name

option_spec: ClassVar[OptionSpec] = {'annotation': <function annotation_option>, 'no-index': <function bool_option>, 'no-value': <function bool_option>, 'noindex': <function bool_option>}

priority = 10

priority if multiple documenters return True from can_document_member

should_suppress_value_header()

update_annotations(parent)

Update __annotations__ to support type_comment and so on.

class sage_docbuild.ext.sage_autodoc.ClassDocumenter(*args: Any)

Bases: DocstringSignatureMixin, ModuleLevelDocumenter

Specialized Documenter subclass for classes.

add_content(more_content)

add_directive_header(sig)

classmethod can_document_member(member, membername, isattr, parent)

document_members(all_members=False)

format_args(**kwargs)

format_signature(**kwargs)

generate(more_content=None, real_modname=None, check_module=False, all_members=False)

get_canonical_fullname()

get_doc()

get_object_members(want_all)

get_overloaded_signatures()

get_variable_comment()

import_object(raiseerror=False)

member_order = 20

order if autodoc_member_order is set to ‘groupwise’

objtype = 'class'

name by which the directive is called (auto…) and the default generated directive name

option_spec: ClassVar[OptionSpec] = {'class-doc-from': <function class_doc_from_option>, 'exclude-members': <function exclude_members_option>, 'inherited-members': <function inherited_members_option>, 'member-order': <function member_order_option>, 'members': <function members_option>, 'no-index': <function bool_option>, 'noindex': <function bool_option>, 'private-members': <function members_option>, 'show-inheritance': <function bool_option>, 'special-members': <function members_option>, 'undoc-members': <function bool_option>}

priority = 15

priority if multiple documenters return True from can_document_member

class sage_docbuild.ext.sage_autodoc.ClassLevelDocumenter(directive: DocumenterBridge, name: str, indent: str = '')

Bases: Documenter

Specialized Documenter subclass for objects on class level (methods, attributes).

resolve_name(modname, parents, path, base)

class sage_docbuild.ext.sage_autodoc.DataDocumenter(directive: DocumenterBridge, name: str, indent: str = '')

Bases: GenericAliasMixin, UninitializedGlobalVariableMixin, ModuleLevelDocumenter

Specialized Documenter subclass for data items.

add_content(more_content)

add_directive_header(sig)

classmethod can_document_member(member, membername, isattr, parent)

document_members(all_members=False)

get_doc()

get_module_comment(attrname)

get_real_modname()

import_object(raiseerror=False)

member_order = 40

order if autodoc_member_order is set to ‘groupwise’

objtype = 'data'

name by which the directive is called (auto…) and the default generated directive name

option_spec: ClassVar[OptionSpec] = {'annotation': <function annotation_option>, 'no-index': <function bool_option>, 'no-value': <function bool_option>, 'noindex': <function bool_option>}

priority = -10

priority if multiple documenters return True from can_document_member

should_suppress_value_header()

update_annotations(parent)

Update __annotations__ to support type_comment and so on.

class sage_docbuild.ext.sage_autodoc.DataDocumenterMixinBase

Bases: object

config: Config

env: BuildEnvironment

modname: str

object: Any

objpath: list[str]

parent: Any

should_suppress_directive_header()

Check directive header should be suppressed.

should_suppress_value_header()

Check :value: header should be suppressed.

update_content(more_content)

Update docstring, for example with TypeVar variance.

class sage_docbuild.ext.sage_autodoc.DecoratorDocumenter(directive: DocumenterBridge, name: str, indent: str = '')

Bases: FunctionDocumenter

Specialized Documenter subclass for decorator functions.

format_args(**kwargs)

objtype = 'decorator'

name by which the directive is called (auto…) and the default generated directive name

priority = -1

priority if multiple documenters return True from can_document_member

class sage_docbuild.ext.sage_autodoc.DocstringSignatureMixin

Bases: object

Mixin for FunctionDocumenter and MethodDocumenter to provide the feature of reading the signature from the docstring.

format_signature(**kwargs)

get_doc()

class sage_docbuild.ext.sage_autodoc.DocstringStripSignatureMixin

Bases: DocstringSignatureMixin

Mixin for AttributeDocumenter to provide the feature of stripping any function signature from the docstring.

format_signature(**kwargs)

class sage_docbuild.ext.sage_autodoc.Documenter(directive: DocumenterBridge, name: str, indent: str = '')

Bases: object

A Documenter knows how to autodocument a single object type. When registered with the AutoDirective, it will be used to document objects of that type when needed by autodoc.

Its objtype attribute selects what auto directive it is assigned to (the directive name is ‘auto’ + objtype), and what directive it generates by default, though that can be overridden by an attribute called directivetype.

A Documenter has an option_spec that works like a docutils directive’s; in fact, it will be used to parse an auto directive’s options that matches the Documenter.

add_content(more_content)

Add content from docstrings, attribute documentation and user.

add_directive_header(sig)

Add the directive header and options to the generated content.

add_line(line, source, *lineno)

Append one line of generated reST to the output.

classmethod can_document_member(member, membername, isattr, parent)

Called to see if a member can be documented by this Documenter.

check_module()

Check if self.object is really defined in the module given by self.modname.

content_indent = '   '

indentation by which to indent the directive content

document_members(all_members=False)

Generate reST for member documentation.

If all_members is True, document all members, else those given by self.options.members.

property documenters: dict[str, type[Documenter]]

Returns registered Documenter classes

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(**kwargs)

Format the argument signature of self.object.

Should return None if the object does not have a signature.

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).

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.

get_sourcename()

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.

member_order = 0

order if autodoc_member_order is set to ‘groupwise’

objtype = 'object'

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>}

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.

priority = 0

priority if multiple documenters return True from can_document_member

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 the zipfile.ZipFile.open method.

sort_members(documenters, order)

Sort the given member list.

titles_allowed = True

true if the generated content may contain titles

class sage_docbuild.ext.sage_autodoc.ExceptionDocumenter(*args: Any)

Bases: ClassDocumenter

Specialized ClassDocumenter subclass for exceptions.

classmethod can_document_member(member, membername, isattr, parent)

member_order = 10

order if autodoc_member_order is set to ‘groupwise’

objtype = 'exception'

name by which the directive is called (auto…) and the default generated directive name

priority = 20

priority if multiple documenters return True from can_document_member

class sage_docbuild.ext.sage_autodoc.FunctionDocumenter(directive: DocumenterBridge, name: str, indent: str = '')

Bases: DocstringSignatureMixin, ModuleLevelDocumenter

Specialized Documenter subclass for functions.

add_directive_header(sig)

annotate_to_first_argument(func, typ)

Annotate type hint to the first argument of function if needed.

classmethod can_document_member(member, membername, isattr, parent)

document_members(all_members=False)

format_args(**kwargs)

format_signature(**kwargs)

member_order = 30

order if autodoc_member_order is set to ‘groupwise’

merge_default_value(actual, overload)

Merge default values of actual implementation to the overload variants.

objtype = 'function'

name by which the directive is called (auto…) and the default generated directive name

class sage_docbuild.ext.sage_autodoc.GenericAliasMixin

Bases: DataDocumenterMixinBase

Mixin for DataDocumenter and AttributeDocumenter to provide the feature for supporting GenericAliases.

should_suppress_directive_header()

update_content(more_content)

sage_docbuild.ext.sage_autodoc.INSTANCEATTR = <object object>

The base class of the class hierarchy.

When called, it accepts no arguments and returns a new featureless instance that has no instance attributes and cannot be given any.

class sage_docbuild.ext.sage_autodoc.MethodDocumenter(directive: DocumenterBridge, name: str, indent: str = '')

Bases: DocstringSignatureMixin, ClassLevelDocumenter

Specialized Documenter subclass for methods (normal, static and class).

add_directive_header(sig)

annotate_to_first_argument(func, typ)

Annotate type hint to the first argument of function if needed.

classmethod can_document_member(member, membername, isattr, parent)

directivetype = 'method'

document_members(all_members=False)

format_args(**kwargs)

get_doc()

import_object(raiseerror=False)

member_order = 50

order if autodoc_member_order is set to ‘groupwise’

merge_default_value(actual, overload)

Merge default values of actual implementation to the overload variants.

objtype = 'method'

name by which the directive is called (auto…) and the default generated directive name

priority = 1

priority if multiple documenters return True from can_document_member

class sage_docbuild.ext.sage_autodoc.ModuleDocumenter(*args: Any)

Bases: Documenter

Specialized Documenter subclass for modules.

add_content(more_content)

add_directive_header(sig)

classmethod can_document_member(member, membername, isattr, parent)

content_indent = ''

indentation by which to indent the directive content

get_module_members()

Get members of target module.

get_object_members(want_all)

import_object(raiseerror=False)

objtype = 'module'

name by which the directive is called (auto…) and the default generated directive name

option_spec: ClassVar[OptionSpec] = {'deprecated': <function bool_option>, 'exclude-members': <function exclude_members_option>, 'ignore-module-all': <function bool_option>, 'imported-members': <function bool_option>, 'inherited-members': <function inherited_members_option>, 'member-order': <function member_order_option>, 'members': <function members_option>, 'no-index': <function bool_option>, 'no-value': <function bool_option>, 'noindex': <function bool_option>, 'platform': <function identity>, 'private-members': <function members_option>, 'show-inheritance': <function bool_option>, 'special-members': <function members_option>, 'synopsis': <function identity>, 'undoc-members': <function bool_option>}

parse_name()

resolve_name(modname, parents, path, base)

sort_members(documenters, order)

class sage_docbuild.ext.sage_autodoc.ModuleLevelDocumenter(directive: DocumenterBridge, name: str, indent: str = '')

Bases: Documenter

Specialized Documenter subclass for objects on module level (functions, classes, data/constants).

resolve_name(modname, parents, path, base)

class sage_docbuild.ext.sage_autodoc.NonDataDescriptorMixin

Bases: DataDocumenterMixinBase

Mixin for AttributeDocumenter to provide the feature for supporting non data-descriptors.

Note

This mix-in must be inherited after other mix-ins. Otherwise, docstring and :value: header will be suppressed unexpectedly.

get_doc()

import_object(raiseerror=False)

should_suppress_value_header()

class sage_docbuild.ext.sage_autodoc.ObjectMember(name: str, obj: Any, *, docstring: str | None = None, class_: Any | None = None, skipped: bool = False)

Bases: object

A member of object.

This is used for the result of \(Documenter.get_module_members()\) to represent each member of the object.

class sage_docbuild.ext.sage_autodoc.Options

Bases: dict[str, Any]

A dict/attribute hybrid that returns None on nonexisting keys.

copy()

class sage_docbuild.ext.sage_autodoc.PropertyDocumenter(directive: DocumenterBridge, name: str, indent: str = '')

Bases: DocstringStripSignatureMixin, ClassLevelDocumenter

Specialized Documenter subclass for properties.

add_directive_header(sig)

classmethod can_document_member(member, membername, isattr, parent)

document_members(all_members=False)

format_args(**kwargs)

get_real_modname()

import_object(raiseerror=False)

Check the existence of uninitialized instance attribute when failed to import the attribute.

member_order = 60

order if autodoc_member_order is set to ‘groupwise’

objtype = 'property'

name by which the directive is called (auto…) and the default generated directive name

priority = 11

priority if multiple documenters return True from can_document_member

class sage_docbuild.ext.sage_autodoc.RuntimeInstanceAttributeMixin

Bases: DataDocumenterMixinBase

Mixin for AttributeDocumenter to provide the feature for supporting runtime instance attributes (that are defined in __init__() methods with doc-comments).

Example:

class Foo:

def __init__(self):

self.attr = None #: This is a target of this mix-in.

RUNTIME_INSTANCE_ATTRIBUTE

get_doc()

import_object(raiseerror=False)

Check the existence of runtime instance attribute after failing to import the attribute.

is_runtime_instance_attribute(parent)

Check the subject is an attribute defined in __init__().

is_runtime_instance_attribute_not_commented(parent)

Check the subject is an attribute defined in __init__() without comment.

should_suppress_value_header()

class sage_docbuild.ext.sage_autodoc.SlotsMixin

Bases: DataDocumenterMixinBase

Mixin for AttributeDocumenter to provide the feature for supporting __slots__.

get_doc()

import_object(raiseerror=False)

isslotsattribute()

Check the subject is an attribute in __slots__.

should_suppress_value_header()

class sage_docbuild.ext.sage_autodoc.UninitializedGlobalVariableMixin

Bases: DataDocumenterMixinBase

Mixin for DataDocumenter to provide the feature for supporting uninitialized (type annotation only) global variables.

get_doc()

import_object(raiseerror=False)

should_suppress_value_header()

class sage_docbuild.ext.sage_autodoc.UninitializedInstanceAttributeMixin

Bases: DataDocumenterMixinBase

Mixin for AttributeDocumenter to provide the feature for supporting uninitialized instance attributes (PEP-526 styled, annotation only attributes).

Example:

class Foo:

attr: int #: This is a target of this mix-in.

get_doc()

import_object(raiseerror=False)

Check the existence of uninitialized instance attribute when failed to import the attribute.

is_uninitialized_instance_attribute(parent)

Check the subject is an annotation only attribute.

should_suppress_value_header()

sage_docbuild.ext.sage_autodoc.annotation_option(arg)

sage_docbuild.ext.sage_autodoc.autodoc_attrgetter(app, obj, name, *defargs)

Alternative getattr() for types

sage_docbuild.ext.sage_autodoc.between(marker, what=None, keepempty=False, exclude=False)

Return a listener that either keeps, or if exclude is True excludes, lines between lines that match the marker regular expression. If no line matches, the resulting docstring would be empty, so no change will be made unless keepempty is true.

If what is a sequence of strings, only docstrings of a type in what will be processed.

sage_docbuild.ext.sage_autodoc.bool_option(arg)

Used to convert flag options to auto directives. (Instead of directives.flag(), which returns None).

sage_docbuild.ext.sage_autodoc.class_doc_from_option(arg)

Used to convert the :class-doc-from: option to autoclass directives.

sage_docbuild.ext.sage_autodoc.cut_lines(pre, post=0, what=None)

Return a listener that removes the first pre and last post lines of every docstring. If what is a sequence of strings, only docstrings of a type in what will be processed.

Use like this (e.g. in the setup() function of conf.py):

from sphinx.ext.autodoc import cut_lines
app.connect('autodoc-process-docstring', cut_lines(4, what={'module'}))

This can (and should) be used in place of automodule_skip_lines.

sage_docbuild.ext.sage_autodoc.exclude_members_option(arg)

Used to convert the :exclude-members: option.

sage_docbuild.ext.sage_autodoc.getdoc(obj, *args, **kwargs)

sage_docbuild.ext.sage_autodoc.identity(x)

sage_docbuild.ext.sage_autodoc.inherited_members_option(arg)

Used to convert the :inherited-members: option to auto directives.

sage_docbuild.ext.sage_autodoc.member_order_option(arg)

Used to convert the :member-order: option to auto directives.

sage_docbuild.ext.sage_autodoc.members_option(arg)

Used to convert the :members: option to auto directives.

sage_docbuild.ext.sage_autodoc.merge_members_option(options)

Merge :private-members: and :special-members: options to the :members: option.

sage_docbuild.ext.sage_autodoc.py_ext_sig_re = re.compile('^ ([\\w.]+::)?            # explicit module name\n          ([\\w.]+\\.)?            # module and/or class name(s)\n          (\\w+)  \\s*             # thing name\n          (?: \\[\\s*(.*)\\s*])?  , re.VERBOSE)

extended signature RE: with explicit module name separated by “::”

sage_docbuild.ext.sage_autodoc.setup(app)