swift-rst-docs

Python library, CLI and Sphinx extension to generate reStructuredText documentation for Swift projects from SourceKitten output files.

Document

Contents

• CLI Usage
• Sphinx
  • Usage
  • Markup extensions
• API Reference
  • Example
  • Generation
  • Parsing
  • Types

Example Output

• MySwiftPackage
  • MySwiftLibrary
  • MyOtherSwiftLibrary

Installation

$ pip install swift-rst-docs

Usage

You need to generate a JSON file with SourceKitten first for swift_rst_docs to parse them.

To reference symbols in your documentation strings, place their full name between 4 backticks. For example: ``MyStructure.hello(world:)`` or ``MySwiftLibrary.MyStructure.hello(world:)`` when referencing from another module or the documentation’s overview text. This will create a link to the symbol’s page.

$ sourcekitten doc [--spm] [-- <swift / xcodebuild arguments>] > documentation.json

You can then use either the CLI or the Python API to generate RST documents. This doesn’t require the use of the Sphinx extension.

If you want more control on your module pages and automatic generation from the JSON files, you can use sphinx_rst_docs as a Sphinx extension.