API Reference

API for generating Swift documentation as restructuredText for HTML output.

Generation

swift_rst_docs.fetch_documents(api_file_path: str, context: GenerationContext)

Fetches symbols from a SourceKitten documentation JSON file path and writes them to swift_rst_docs.GenerationContext.body.

Parameters:

  • api_file_path – The path to the SourceKitten documentation JSON file.

  • context – The generation context.

swift_rst_docs.generate_documentation(context: GenerationContext) → list[Page]

Generates and returns all the documentation pages for the passed generation context. swift_rst_docs.fetch_documents() should have been called first. If multiple modules were fetched, will generate an index page for each module.

Parameters:

context – The generation context.

Return type:

list[Page]

class swift_rst_docs.GenerationContext(index_title: str, overview: str | None = None, min_accessibility: Accessibility = Accessibility.PUBLIC, documented_objects: list[str] | None = None, documented_symbols: list[str] | None = None)

A generation context contains metadata and options for the generation of the documentation, as well as the symbols information fetched by swift_rst_docs.fetch_documents().

body: list[Symbol]

Top level symbols fetched by swift_rst_docs.fetch_documents().

documented_objects: list[str] | None

An optional list of documented files (with .swift extension). If None, all files in the module will be documented. swift_rst_docs.fetch_documents() checks if the fetched file paths end with any of the values of this list, so you can write just the file names, or the paths relative to any directory in the source code to disambiguate between modules.

documented_symbols: list[str] | None

An optional list of top level documented symbol names. If None, all symbols will be documented.

find(symbol_name: str, module_name: str | None) → str | None

Finds a symbol name in swift_rst_docs.GenerationContext.fullnames and returns its USR value if found.

Parameters:

  • symbol_name – The symbol name to find.

  • module_name – An optional module name to use as context. If not None, symbol_name can omit the module name.

Return type:

Optional[str]

fullnames: dict[str, str]

A dictionary mapping full symbols names to their documentation’s USR. A USR is an unique identifier of a symbol in the documentation, which corresponds to the file name (without the extension) in the documentation’s root directory by replacing “:” with “_”.

This value is written by swift_rst_docs.fetch_fullnames().

index_title: str

The title of the main page.

min_accessibility: Accessibility

Minimum accessibility for symbols to be documented.

overview: str

A text written into the main page.

swift_rst_docs.main()

CLI entry point.

Parsing

swift_rst_docs.parse(body: dict, context: GenerationContext) → Symbol

Parses a symbol from the documentation JSON file and returns it.

Parameters:

  • body – The dictionary value of the symbol.

  • context – The generation context to write to.

Return type:

Symbol

swift_rst_docs.fetch_fullnames(body: dict, context: GenerationContext, parent_names: list[str] = [])

Fetches a symbol’s full name (including their module) and all their sub declarations recursively, mapped to their USR value and writes them to GenerationContext.fullnames.

Parameters:

body – The dictionary value of the symbol.

Para context:

The generation context to write to.

Parent_names:

List of parents containing the fetched declaration.

Replaces symbol references with a link to their html page and returns the result. swift_rst_docs.fetch_documents() should have been called for links to be correctly generated.

Parameters:

  • text – The documentation text to parse.

  • module_name – The current module name (can be None). Finds the symbol in the current module first, then in the global scope if the module name is specified in the symbol’s name.

  • context – The generation context.

Return type:

str

swift_rst_docs.highlight_statement(statement: AnnotatedDeclaration, prettify: bool, remove_type: bool, context: GenerationContext) → str

Highlights a statement’s declaration with pygments and returns it as a raw:: html block. Also replaces any USR in the statement’s declaration with links to the corresponding documentation pages if symbols are already fetched into the generation context.

Parameters:

  • statement – The statement to highlight.

  • prettify – Whether to prettify the code.

  • remove_type – Whether to remove the type.

  • context – The generation context.

Return type:

str

swift_rst_docs.prettify_swift_declaration(decl: str, indent: str = '    ') → str

Splits and returns a Swift declaration into multiple lines.

Decl:

A Swift declaration.

Indent:

Indentation to use.

Return type:

str

Types

class swift_rst_docs.Accessibility(*values)

A symbol’s accessibility attribute.

FILEPRIVATE = 'source.lang.swift.accessibility.fileprivate'

Restricted to the source file.

INTERNAL = 'source.lang.swift.accessibility.internal'

Restricted to the module.

OPEN = 'source.lang.swift.accessibility.open'

Open for inheritance.

PRIVATE = 'source.lang.swift.accessibility.private'

Restricted to the containing declaration.

PUBLIC = 'source.lang.swift.accessibility.public'

Accessible from another module.

UNKNOWN = 'unknown'

Unknown accessibility.

property order: int

Order of accessibility. Higher value means more accessible.

Return type:

int

class swift_rst_docs.AnnotatedDeclaration(declaration: str)

A type annotated declaration, initialized from an XML string.

chunks: list[Annotation]

The typed chunks of the declaration.

parsed: str

The full parsed declaration as plain text.

class swift_rst_docs.Annotation(chunk: str, usr: str | None)

An annotated part of a declaration.

chunk: str

The chunk of code in the declaration.

usr: str | None

An optional type USR value the chunk corresponds to.

class swift_rst_docs.DeclarationKind(*values)

A kind of declaration.

CLASS = 'source.lang.swift.decl.class'

A class.

CLASS_METHOD = 'source.lang.swift.decl.function.method.class'

A class method.

CLASS_VARIABLE = 'source.lang.swift.decl.var.class'

A class variable.

ENUM = 'source.lang.swift.decl.enum'

An enumeration.

ENUM_ELEMENT = 'source.lang.swift.decl.enumelement'

An enumeration case.

EXTENSION = 'source.lang.swift.decl.extension'

An extension.

FUNCTION = 'source.lang.swift.decl.function.free'

A global function.

INSTANCE_METHOD = 'source.lang.swift.decl.function.method.instance'

An instance method.

INSTANCE_VARIABLE = 'source.lang.swift.decl.var.instance'

An instance variable.

LOCAL_VARIABLE = 'source.lang.swift.decl.var.local'

A local variable.

PROTOCOL = 'source.lang.swift.decl.protocol'

A protocol.

STATIC_METHOD = 'source.lang.swift.decl.function.method.static'

A static method.

STATIC_VARIABLE = 'source.lang.swift.decl.var.static'

A static variable.

STRUCT = 'source.lang.swift.decl.struct'

A structure.

UNKNOWN = 'unknown'

An unknown declaration.

class swift_rst_docs.Documentation(body: str, context: GenerationContext)

The documentation of a symbol, initialized from an XML string.

comment: str

The first line of the comment string.

discussion: str | None

The rest of the comment string.

name: str

The relative name of the symbol.

parameters: list[dict[str, str]]

A list of parameters witht their documentation. Each value has name and a description key.

result: str | None

The description of the return value.

usr: str

The unique identifier of the symbol. Corresponds to its page file name (without the extension) by replacing “:” with “:”.

class swift_rst_docs.MARK(body: dict)

A mark (MARK: -) comment in the source file. Used to separate symbols into categories.

name: str

Name of the section.

class swift_rst_docs.MainPage(contents: str, context: GenerationContext)

The main index page of the whole documentation. This is the same as the module index page when there is only one module.

class swift_rst_docs.ModulePage(module_name: str, contents: str, context: GenerationContext)

The index page for a module.

class swift_rst_docs.Page(item: Symbol, context: GenerationContext)

A Swift documentation page in RST format.

Initializing from a swift_rst_docs.Symbol and a swift_rst_docs.GenerationContext automatically generates the contents. swift_rst_docs.fetch_documents() should have been called for links to be correctly generated.

contents: str

The contents of the generated page.

file_name: str

File name with extension.

class swift_rst_docs.Structure(body: dict)

A structure in the document. Initialized from a dictionary decoded from the documentation JSON file.

name: str

The name of the structure. Corresponds to the key.name key of the body passed to the initializer.

class swift_rst_docs.Symbol(body: dict, context: GenerationContext)

A source code symbol.

accessibility: Accessibility

Symbol’s accessibility level.

context: GenerationContext

The generation context fetching this symbol.

declaration: AnnotatedDeclaration

Type annotated declaration.

documentation: Documentation | None

An optional documentation attached to the symbol.

inherited_types: list[str] | None

Types the symbol inherits from.

kind: DeclarationKind

Kind of declaration.

module_name: str

The name of the module exporting this symbol.

name: str

Relative name of the symbol.

substructure: list[Structure]

Sub-declarations of the symbol.

usr: str | None

The unique identifier of the symbol. Corresponds to its page file name (without the extension) by replacing “:” with “:”.