Swiftpack.co - Package - SwiftDocOrg/swift-doc

swift-doc

CI

A package for generating documentation for Swift projects.

Given a directory of Swift files, swift-doc generates HTML or CommonMark (Markdown) files for each class, structure, enumeration, and protocol as well as top-level type aliases, functions, and variables.

Example Output

Requirements

Command-Line Utility

swift-doc can be used from the command-line on macOS and Linux.

Installation

Homebrew

Run the following command to install using Homebrew:

$ brew install swiftdocorg/formulae/swift-doc

Manually

Run the following commands to build and install manually:

$ git clone https://github.com/SwiftDocOrg/swift-doc
$ cd swift-doc
$ make install

Usage

OVERVIEW: A utility for generating documentation for Swift code.

USAGE: swift doc <subcommand>

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

SUBCOMMANDS:
  generate                Generates Swift documentation
  coverage                Generates documentation coverage statistics for Swift
                          files
  diagram                 Generates diagram of Swift symbol relationships

Note: The swift driver provides extensibility through subcommands. If you type an unknown subcommand like swift foo, the system looks for a command called swift-foo in your PATH. This mechanism allows swift-doc to be run either directly or as swift doc.

swift-doc generate

OVERVIEW: Generates Swift documentation

USAGE: swift doc generate [<inputs> ...] --module-name <module-name> [--output <output>] [--format <format>] [--base-url <base-url>]

ARGUMENTS:
  <inputs>                One or more paths to Swift files 

OPTIONS:
  -n, --module-name <module-name>
                          The name of the module 
  -o, --output <output>   The path for generated output (default:
                          .build/documentation)
  -f, --format <format>   The output format (default: commonmark)
  --base-url <base-url>   The base URL used for all relative URLs in generated
                          documents. (default: /)
  -h, --help              Show help information.

The generate subcommand takes one or more paths and enumerates them recursively, collecting all Swift files into a single "module" and generating documentation accordingly.

$ swift doc generate path/to/SwiftProject/Sources --module-name SwiftProject
$ tree .build/documentation
$ documentation/
├── Home
├── (...)
├── _Footer.md
└── _Sidebar.md

By default, output files are written to .build/documentation in CommonMark / GitHub Wiki format, but you can change that with the --output and --format option flags.

$ swift doc generate path/to/SwiftProject/Sources --module-name SwiftProject --output Documentation --format html
$ Documentation/
├── (...)
└── index.html

swift-doc coverage

OVERVIEW: Generates documentation coverage statistics for Swift files

USAGE: swift doc coverage [<inputs> ...] [--output <output>]

ARGUMENTS:
  <inputs>                One or more paths to Swift files 

OPTIONS:
  -o, --output <output>   The path for generated report 
  -h, --help              Show help information.

The coverage subcommand generates documentation coverage statistics for Swift files.

$ git clone https://github.com/SwiftDocOrg/SwiftSemantics.git

$ swift run swift-doc coverage SwiftSemantics/Sources --output "dcov.json"
$ cat dcov.json | jq ".data.totals"
{
  "count": 207,
  "documented": 199,
  "percent": 96.1352657004831
}

$ cat dcov.json | jq ".data.symbols[] | select(.documented == false)"
{
  "file": "SwiftSemantics/Supporting Types/GenericRequirement.swift",
  "line": 67,
  "column": 6,
  "name": "GenericRequirement.init?(_:)",
  "type": "Initializer",
  "documented": false
}
...

While there are plenty of tools for assessing test coverage for code, we weren't able to find anything analogous for documentation coverage. To this end, we've contrived a simple JSON format inspired by llvm-cov.

If you know of an existing standard that you think might be better suited for this purpose, please reach out by opening an Issue!

swift-doc diagram

OVERVIEW: Generates diagram of Swift symbol relationships

USAGE: swift doc diagram [<inputs> ...]

ARGUMENTS:
  <inputs>                One or more paths to Swift files 

OPTIONS:
  -h, --help              Show help information.

The diagram subcommand generates a graph of APIs in DOT format that can be rendered by GraphViz into a diagram.

$ swift run swift-doc diagram Alamofire/Source > Alamofire.gv
$ head Alamofire.gv
digraph Anonymous {
  "Session" [shape=box];
  "NetworkReachabilityManager" [shape=box];
  "URLEncodedFormEncoder" [shape=box,peripheries=2];
  "ServerTrustManager" [shape=box];
  "MultipartFormData" [shape=box];

  subgraph cluster_Request {
    "DataRequest" [shape=box];
    "Request" [shape=box];

$ dot -T svg Alamofire.gv > Alamofire.svg

Here's an excerpt of the graph generated for Alamofire:

Excerpt of swift-doc-api Diagram for Alamofire

GitHub Action

This repository also hosts a GitHub Action that you can incorporate into your project's workflow.

The CommonMark files generated by swift-doc are formatted for publication to your project's GitHub Wiki, which you can do with github-wiki-publish-action. Alternatively, you could specify HTML format to publish documentation to GitHub Pages or bundle them into a release artifact.

Inputs

  • inputs: A path to a directory containing Swift (.swift) files in your workspace. (Default: "./Sources")
  • format: The output format ("commonmark" or "html") (Default: "commonmark")
  • module-name: The name of the module.
  • base-url: The base URL for all relative URLs generated in documents. (Default: "/")
  • output: The path for generated output. (Default: "./.build/documentation")

Example Workflow

# .github/workflows/documentation.yml
name: Documentation

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v1
      - name: Generate Documentation
        uses: SwiftDocOrg/swift-doc@master
        with:
          inputs: "Sources"
          module-name: MyLibrary
          output: "Documentation"
      - name: Upload Documentation to Wiki
        uses: SwiftDocOrg/github-wiki-publish-action@v1
        with:
          path: "Documentation"
        env:
          GH_PERSONAL_ACCESS_TOKEN: ${{ secrets.GH_PERSONAL_ACCESS_TOKEN }}

Development

Web Assets

CSS assets used by the HTML output format are processed and generated by PostCSS. To make changes to these assets, you'll need to have Node.js and a package manager, such as npm, installed on your machine.

Navigate to the .node directory and run npm install to download the required tools and libraries.

$ cd .node
$ npm install

Note: package.json is located at a hidden .node subdirectory to prevent Xcode from displaying or indexing the contents of node_modules when opening the main project.

From the .node directory, run the watch script to start watching for changes to files in the Assets folder. Whenever an asset source file is added, removed, or updated, its corresponding (unoptimized) product is automatically generated in the Resources folder.

$ npm run watch

When you're happy with the results, commit any changes to the source files in Assets as well as the generated files in Resources.

$ git add Assets Resources
$ git commit

Release Process

The following information is primarily for the benefit of project maintainers. That said, if you have any suggestions for how to improve this process, please let us know by opening an issue.

Follow these steps to release a new version of swift-doc:

  • ☑ Verify that the latest commit passed all CI checks.
  • ☑ Update the Changelog by creating a new heading for the release and modifying the last path component for the unreleased link reference.
  • ☑ Update the version constant in the command-line executable.
  • ☑ Create a new commit with the message "Bump version to $VERSION", where $VERSION is a SemVer-compatible version number.
  • ☑ Tag that commit with the tag name "$VERSION"
  • ☑ Run the command git push origin master --tags
  • ☑ Create a new release that corresponds to the new tag.

License

MIT

Contact

Mattt (@mattt)

Github

link
Stars: 1313

Used By

Total: 0

Releases

1.0.0-beta.5 - 2020-10-07 11:29:33

Added

  • Added support for Swift 5.3. #183 by @MaxDesiatov and @mattt.

Fixed

  • Fixed missing GraphViz dependency in Dockerfile. #180 by @MaxDesiatov.
  • Fixed listing of function parameters, when generating CommonMark documentation. #170 by @domcorvasce.
  • Fixed version number for swift-doc command. #159 by @mattt.
  • Fixed relationship diagram to prevent linking to unknown symbols. #178 by @MattKiazyk.
  • Fixed problems in CommonMark output related to escaping emoji shortcode. #167 by @mattt.

Changed

  • Changed GitHub Action to use prebuilt Docker image. #185 by @mattt and @MaxDesiatov.

- 2020-07-31 22:21:41

Added

  • Added icon for associated type symbols. #145 by @mattt.

Changed

  • Changed HTML output to show scrollbars only when necessary. #132 by @andrewchang-bird.

Fixed

  • Fixed runtime error related to networking and processes on Ubuntu Linux. #140 by @JaapWijnen.
  • Fixed whitespace of code listings. #144 by @mbrandonw.
  • Fixed crash when attempting to generate paths with no base URL specified. #127 by @mattpolzin, @kareman, and @mattt.
  • Fixed display of sidebar icons. #145 by @mattt.
  • Fixed inclusion of non-public subclasses of public superclasses. #131 by @MattKiazyk. #116 by @ApolloZhu.
  • Fixed display of bullet list items in documentation discussion parts. #130 by @mattt.
  • Fixed file and directory unexpected permissions. #146 by @niw.
  • Fixed rendering of colon sequences in function signatures as emoji shortcodes (e.g. :on: → 🔛). #149 by @mattt.
  • Fixed declarations for properties without explicit type annotations. #150 by @mattt.
  • Fixed visual regression for adjacent linked tokens in code block. #152 by @mattt.
  • Fixed regression that caused nodes in relationships graph to not have links to their corresponding symbol documentation. #153 by @mattt.
  • Fixed markup for parameter descriptions in HTML output. #156 by @mattt.

1.0.0-beta.3 - 2020-05-19 13:46:27

Added

  • Added --base-url option. #65 by @kean and #93 by @mattt.
  • Added asset pipeline for CSS assets. #49 by @kaishin.
  • Add swift-doc version number to command and generated output. #94 by @mattt.

Changed

  • Changed Home page to display globals for HTML format. #81 by @kean.
  • Changed README to clarify use of swift-doc vs. swift doc on the command line. #89 by @mattt.
  • Changed the generate command to emit a warning if no source files are found. #92 by @heckj
  • Changed CommonMark format output of Home page to include summaries alongside top-level symbols, when available. #97 by @mattt.
  • Changed logging behavior to better communicate errors encountered when generating relationship graphs using GraphViz. #100 by @mattt.
  • Changed HTML format output of Home page to move enumeration cases under initializers. #103 by @mattt.

Fixed

  • Fixed relationship handling for members of nested types. #62 by @victor-pavlychko.
  • Fixed rendering of type relationships section when no graph data is available. #62 by @victor-pavlychko.
  • Fixed rendering of protocol requirements in the HTML version. #76 by @victor-pavlychko.
  • Fixed default location of sources reference in README #92 by @heckj
  • Fixed indentation of code examples in HTML output. #114 by @samsymons
  • Fixed icons for symbols in HTML output. #115 by @samsymons

0.0.2 - 2020-04-08 16:00:16

Added

  • Added "Installation" section to README. 7784bef by @mattt.
  • Added experimental swift-api-diagram executable. 017e920 by @mattt.

Fixed

  • Fixed division by zero when calculating documentation coverage. #5 by @mattt.
  • Fixed treatment of directories with .swift suffix. #14 by @mattt.
  • Fixed errors in README. #4 by @Dinsen. #6 by @HeEAaD. #10 by @morqon

0.0.3 - 2020-04-08 16:00:05

Added

  • Added CI workflow. ce40367 by @mattt.
  • Added documentation workflow. a47f178 by @mattt.

Changed

  • Changed documentation generation to filter non-public symbols. 3af57a6 by @mattt.

- 2020-04-08 15:59:51

Changed

  • Changed Package.swift to include SwiftDoc library product in manifest. f852a14 by @mattt.
  • Changed documentation workflow to generate docs for SwiftDoc sources only. da04436 by @mattt.

Fixed

  • Fixed generation to return symbols in consistent order. 97b2347 by @mattt.
  • Fixed how enumeration cases are considered to have public access level. 774faf6 by @mattt.

- 2020-04-08 15:59:13

Added

  • Added initial test suite for SwiftDoc target. #17 by @mattt.

Changed

  • Changed command-line interface to use swift-argument-parser. #20 by @mattt.

Fixed

  • Fixed treatment of members of public protocol to be considered public symbols. #17 by @mattt.

Removed

  • Removed api-inventory subcommand. (This functionality can now be found in its own repository: https://github.com/SwiftDocOrg/swift-api-inventory) #17 by @mattt.

- 2020-04-08 15:58:52

Changed

  • Changed documentation workflow to use github-wiki-publish-action@v1. 4525b8e by @mattt.

1.0.0-beta.1 - 2020-04-08 15:58:34

Added

  • Added HTML output format. #21 by @mattt.

Changed

  • Breaking Change Changed minimum Swift version requirements to 5.2 or later. #21 by @mattt.
  • Changed command-line interface to provide functionality through subcommands. #21 by @mattt.
  • Changed Package.swift to add swift-doc executable and SwiftDoc library to the list of package products. #21 by @mattt.

- 2020-04-08 15:57:59

Changed

  • Breaking Change Changed the SwiftDoc GitHub Action to require a secret named GH_PERSONAL_ACCESS_TOKEN (previously GITHUB_PERSONAL_ACCESS_TOKEN). According to the GitHub Help article "Creating and storing encrypted secrets":

    Secret names cannot include any spaces or start with the GITHUB_ prefix. 8837d82 by @mattt.

  • Breaking Change Changed the SwiftDoc GitHub Action to require a module-name parameter and accepts a format parameter. b231c07 by @mattt.
  • Changed output for CommonMark format to omit Home page for output with only a single page. #55 by @mattt.
  • Changed output for CommonMark format to nest sections in Members component. #55 by @mattt.
  • Changed output for CommonMark format to remove initializer clauses from variable and enumeration case declarations. #55 by @mattt.
  • Changed CI tests to build and run with a release configuration for consistency with the executable built with make install. #51 by @mattt.
  • Changed use of print statements, replacing them with a formal logging infrastructure. #52 by @mattt.

Fixed

  • Fixed bug in SourceFile.Visitor that caused incorrect results when determining the context of symbols parsed from Swift source files. #51 by @mattt.
  • Fixed SwiftDoc GitHub action to build against latest version of swift-doc. 5c0e4e0 by @mattt
  • Fixed output for CommonMark format to escape GitHub Emoji shortcodes #55 by @mattt.
  • Fixed output for CommonMark format to remove duplicate headings for global symbol pages. #55 by @mattt.
  • Fixed documentation for SwiftDoc GitHub Action to clarify that only a single path can be specified for the input parameter. c34ccc1 by @mattt (#19).
  • Fixed coverage subcommand description. #16 by @rastersize.

- 2020-01-27 14:08:58