Sphinx¶

Besides generating static documents, swift-rst-docs supports integration with Sphinx as extension. It automatically generates documents for every symbol, but you control where to index them through the swift:module directive. There is also a swift:symbol role for linking documentation pages.

Usage¶

To generate Swift documentation with Sphinx, swift-rst-docs still requires SourceKitten JSON documentation files. It looks for them recursively in every _api directory in the documentation’s source directory. swift-rst-docs temporarily generates the documents there.

The extension must be included in the documentation’s configuration file for documents to be automatically generated.

extensions = ["swift_rst_docs", ...]

The directory API documentations are searched in can be changed through the swift_rst_docs.sphinx.API_DIRECTORY_NAME variable:

import swift_rst_docs
swift_rst_docs.sphinx.API_DIRECTORY_NAME = "_swift_api"

Markup extensions¶

reStructuredText extensions for Swift documentation.

:swift:symbol:

References a symbol’s documentation page from its full name. The module name can be deduced automatically if there is only one symbol with the same name accross modules.

Arguments

The full symbol’s name, with or without its module name.

Usage

:swift:symbol:`MySwiftLibrary.MyStructure.hello(world:)`

.. swift:module::

Writes a toctree listing a module’s symbols with their documentation comments. If the :members: option is present, all symbols are included, if not, every desired symbol must be included as the contents of the directive.

Arguments

The documented module name.

Options

declaration If present, includes the module’s import statement.
members If present, includes all the module’s symbols ignoring the directive’s content.

Contents

Optionally, every included symbol.

Usage

Includes all symbols and the module’s import statement:

.. swift:module:: MySwiftLibrary
   :members:
   :declaration:

Includes the specified symbols only:

.. swift:module:: MySwiftLibrary

   MyStructure
   MyProtocol
   Animal