Sage autodoc extension - Documentation System

Skip to content
Back to top
View this page
Edit this page

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

- François Bissey (2025-02-24): Remove python 3.9 support hacks, making us closer to upstream

- François Bissey (2025-03-18): rebased on sphinx 8.2.3

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-index-entry': <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>, 'no-index-entry': <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-index-entry': <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>, 'no-index-entry': <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-index-entry': <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, 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_: Any
  docstring: str | None
  object: Any
  skipped: bool

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(obj, name, registry, *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)