本页内容

Guidedog / 文档 0.2.0

autodoc¶

Package autodoc generates the reStructuredText that Sphinx’s sphinx.ext.autodoc generates (Sphinx 9.1), from Python source analysed by lib/pyscan instead of imported modules: the same directives (“.. py:class:: Name(signature)” with :module:, :canonical:, “Bases: …”), docstrings prepared as prepare_docstring prepares them, and members chosen, filtered, and ordered as autodoc’s options say. What static analysis cannot know (compiled modules, objects made at run time, members of classes outside the source roots) is reported as a note naming the object, never guessed silently.

It is a host library: it reads files through pyscan and allocates with the context allocator, freeing none of it, so a host runs it in an arena, the same as pyscan’s: a Session and every Result live until the arena is freed.

Types

autodoc.Config :: struct¶

Config holds the conf.toml settings autodoc reads, with Sphinx’s names and defaults (see default_config).

autoclass_content: string¶: “class”, “init”, “both”.

autodoc_class_signature: string¶: “mixed”, “separated”.

autodoc_default_options: []Default_Option ¶

autodoc_docstring_signature: bool¶

autodoc_inherit_docstrings: bool¶

autodoc_member_order: string¶: “alphabetical”, “bysource”, “groupwise”.

autodoc_mock_imports: []string¶

autodoc_preserve_defaults: bool¶

autodoc_typehints: string¶: “signature”, “description”, “none”, “both”.

autodoc_typehints_description_target: string¶: “all”, “documented”, “documented_params”.

autodoc_typehints_format: string¶: “short”, “fully-qualified”.

autodoc_type_aliases: []Type_Alias ¶

autodoc_use_type_comments: bool¶

python_display_short_literal_types: bool¶

strip_signature_backslash: bool¶

tab_width: int¶

typehint_fields: bool¶: typehint_fields writes the fields of autodoc_typehints = “description” into the text (true by default); Sphinx adds them to the parsed field lists instead, so comparisons with its generated text turn it off.

autodoc.Default_Option :: struct¶

Default_Option is one autodoc_default_options entry: a value, or true for a flag.

name: string¶

value: string¶

flag: bool¶: the setting is true: the option is given without a value.

autodoc.Message :: struct¶

Message is a problem to report where the directive stands, Elm-style.

severity: Severity ¶

code: string¶

title: string¶

text: string¶

hint: string¶

autodoc.Option :: struct¶

Option is a directive option as written; value is “” for a flag.

name: string¶

value: string¶

autodoc.Request :: struct¶

Request is one autodoc directive: its name (autoclass, automodule, …), argument, options, content, and the reader’s context (the current py:module and py:class).

directive: string¶

argument: string¶

options: []Option ¶

content: []string¶

module: string¶

class: string¶

autodoc.Result :: struct¶

Result is the generated reST (lines without line breaks; empty when there is nothing to add) and the messages about it.

lines: [dynamic]string¶

messages: [dynamic]Message ¶

autodoc.Session :: struct¶

Session is autodoc’s state across the directives of one build: the analysed project, and the modules whose analyser annotations autodoc has merged into their classes (as _ensure_annotations_from_type_comments does the first time it documents a data or attribute from them), which changes the members found afterwards.

project: ^py.Project ¶

merged: map[string]bool¶

autodoc.Severity :: enum u8¶

Note¶

Warning¶

Error¶

autodoc.Type_Alias :: struct¶

name: string¶

target: string¶

Procedures

autodoc.default_config :: proc() -> Config ¶: default_config is Sphinx 9.1’s defaults for the settings autodoc reads.

autodoc.document :: proc(session: ^Session, config: ^Config, request: Request) -> Result ¶: document generates the reST of one autodoc directive, as AutodocDirective.run does before parsing it: the lines, and messages about them (an unknown directive or a bad option is an Error and no lines; what analysis cannot know is a note naming the object; never a panic). Modules are analysed through the session’s project as needed; the result lives in the context arena.

autodoc.session_init :: proc(s: ^Session, project: ^py.Project)¶: session_init starts a session over an analysed project, which it borrows for the session’s life; its map lives in the context arena.