本页内容

Guidedog / 文档 0.2.0

readers/sphinx

Package sphinx reads reStructuredText with the Sphinx layer: Sphinx’s directives, roles, and domains (GDS “Guidedog: everything Sphinx does, the Odin way”), implemented independently on the base reader’s extension interface. It produces the shapes of lib/core/AST.md, “Sphinx layer”; cross-document work (toctrees, cross-references, numbering) is left to the project host. The same handlers serve Markdown (MyST) read by the commonmark reader: see markdown.odin.

Types

sphinx.Autodoc_Message :: struct

Autodoc_Message is a problem the host found, reported at the directive.

severity: gd.Severity

code: string

title: string

message: string

hint: string

sphinx.Autodoc_Option :: struct

name: string

value: string

“” for a flag.

sphinx.Autodoc_Provider :: struct

Autodoc_Provider belongs to the caller’s trust boundary and may allocate.

procedure: proc(user: rawptr, request: ^Autodoc_Request) -> Autodoc_Result

user: rawptr

sphinx.Autodoc_Request :: struct

Autodoc_Request is one autodoc directive and the context it needs: the current py:module and py:class (ref_context) and the document.

directive: string

“autoclass”

argument: string

options: []Autodoc_Option

content: string

the directive’s content, lines joined with “\n”.

module: string

class: string

docname: string

sphinx.Autodoc_Result :: struct

Autodoc_Result borrows host memory valid for the whole conversion. name names the generated text as a source (for diagnostics), such as “<autodoc flask.Flask>”.

name: string

text: string

messages: []Autodoc_Message

sphinx.Config :: struct

Config holds the conf.toml settings that reading needs, with Sphinx’s names. It reaches the reader through gd.Read_Options.extension. Start from default_config: several defaults are true. Settings that the base reader owns (smart quotes, PEP and RFC base URLs, trimmed footnote reference space, language) live in settings.

using settings: rst.Settings

docname: string

the document’s name, e.g. “usage/intro”.

default_role: string

“” means Docutils’ title-reference.

primary_domain: string

“py”; “” means none.

highlight_language: string

“default”.

extlinks: []Extlink

rst_prolog: string

parsed before every document.

rst_epilog: string

parsed after every document.

numfig: bool

math_number_all: bool

todo_include_todos: bool

show_authors: bool

add_function_parentheses: bool

true.

add_module_names: bool

true.

toc_object_entries: bool

true: objects have table of contents entries.

toc_object_entries_show_parents: Toc_Parents

manpages_url: string

“{page}”, “{section}”, “{path}” substituted.

option_emphasise_placeholders: bool

trim_doctest_flags: bool

true: doctest flags and <BLANKLINE> are hidden.

version: string

The default substitutions |version|, |release|, and |today|, for documents that do not define them: the short version, the full release, and today’s date already formatted (Sphinx’s today, or today_fmt applied).

release: string

today: string

intersphinx: bool

sphinx.ext.intersphinx: the :external: roles are read when it is on, and an external role naming intersphinx_resolve_self is an ordinary reference.

intersphinx_resolve_self: string

labels: ^gd.Labels

The group names of info fields (“Parameters”, “Returns”) in the document’s language, as a host translates its labels; nil for English.

object_types: []Object_Type

Directives and roles the project declares (see object_types.odin), and other names for directives.

directive_aliases: []Directive_Alias

autodoc: Autodoc_Provider

sphinx.ext.autodoc: the host that generates what autodoc directives stand for; nil when the extension is off. See autodoc.odin.

odin_autodoc: Autodoc_Provider

The odin domain’s generating directives (odin:autopackage, …): the host that reads the Odin source; nil leaves them unknown.

sphinx.Directive_Alias :: struct

name: string

“django-admin-option” names “option”; a target may name

target: string

“django-admin-option” names “option”; a target may name

sphinx.Extlink :: struct

Extlink is one sphinx.ext.extlinks entry: :name:part links to url with %s replaced by part; caption, when set, is the link text with %s replaced likewise.

name: string

url: string

caption: string

sphinx.Markdown :: struct

Markdown serves the commonmark reader with this layer’s directives and roles, the same handlers that serve reStructuredText: the reader parses MyST Markdown and hands each directive and role here (commonmark.Extension); they run on an embedded reStructuredText parser whose host is the Markdown reader (rst.Host), so their nested content is parsed as Markdown again. eval-rst parses its content as reStructuredText. The document is resolved as reStructuredText is (references, footnotes, targets, bibliographic fields, smart quotes).

Use: markdown_settings(&m, config, myst) gives the reader settings to pass as gd.Read_Options.extension to the “commonmark” reader; m must outlive the read.

config: Config

settings: cm.Settings

ext: cm.Extension

state: State

parser: rst.Parser

host: rst.Host

reader: ^cm.Host

sphinx.Object_Type :: struct

directive: string

“setting”

role: string

“setting”; “” for none.

index: string

Sphinx’s indextemplate, “pair: %s; setting”; “” for none.

target: bool

add_crossref_type: a target and an index entry, no description.

first_word: bool

the object’s name is the signature up to its first space.

display: string

how the signature is shown, “%s” for it; “” shows it as written.

program: bool

the name becomes the program options that follow belong to.

sphinx.Toc_Parents :: enum u8

Toc_Parents is toc_object_entries_show_parents: how much of an object’s hierarchy its table of contents entry shows.

Domain

as the domain names it: Python’s Class.method, C++’s enclosing objects.

Hide

the object’s own name.

All

every part: module.Class.method, ns::Class::f.

Procedures

sphinx.default_config :: proc() -> Config

default_config returns Sphinx’s defaults, with the base reader’s default_settings and smart quotes on. The value owns nothing; fields a caller sets must outlive the read.

sphinx.markdown_settings :: proc(m: ^Markdown, config: Config, myst: cm.Settings) -> ^cm.Settings

markdown_settings prepares m for one read of a Markdown document with the Sphinx configuration config and the MyST settings myst, and returns the reader settings. It copies both into m; the result points into m, so m must outlive the read and serves one read at a time. It cannot fail.

sphinx.read :: proc(ctx: ^gd.Read_Context) -> gd.Status

read reads reStructuredText with the Sphinx layer. ctx.options.extension is a ^Config (gd.read_extension), or empty for default_config; another type is refused with Invalid_Input. The read copies the Config and keeps nothing of it afterwards; its tables live in scratch, released before it returns. Otherwise it fails as rst.read.

sphinx.read_inline :: proc(ctx: ^gd.Read_Context, span: gd.Source_Span) -> gd.Status

read_inline parses a span of ctx.source as reStructuredText inline content with Sphinx’s roles, for a translated message (gd.Read_Inline_Proc). rst_prolog and rst_epilog do not apply to a message. Settings, ownership, and failures are read’s.

sphinx.reader :: proc() -> gd.Reader

reader returns the “sphinx” reader descriptor, for a gd.Registry. It is a value with no state: registering it twice or copying it is harmless.

Constants

sphinx.CONFORMANCE :: gd.Conformance.Partial

sphinx.MAX_OBJECT_TYPES :: 64

sphinx.VERSION :: "0.1.0"