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]

swift_rst_docs.GenerationContext(index_title: str, overview: str = 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().

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.

class swift_rst_docs.AnnotatedDeclaration(declaration: str)

A type annotated declaration, initialized from an XML string.

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

An annotated part of a declaration.

class swift_rst_docs.DeclarationKind(*values)

A kind of declaration.

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

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

class swift_rst_docs.MARK(body: dict)

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

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.

class swift_rst_docs.Structure(body: dict)

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

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

A source code symbol.