Generation

High level interface for document generation.

API for generating Swift documentation as restructuredText for HTML output.

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, index: bool = True) → 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.

The ìndex argument controls whether an index page should be generated. If it’s True and only one module is documented, the index page will correspond to that module. If it’s False, the module page will be generated in its own file as it happens with multiple modules but no ‘index.rst’ page will be generated.

Parameters:

  • context – The generation context.

  • index – Whether to generate an index page.

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.