diff --git a/README.md b/README.md index c55d232c..1793d88c 100644 --- a/README.md +++ b/README.md @@ -4,20 +4,15 @@ A package for generating documentation for Swift projects. -**This project is under active development -and is expected to change significantly before its first stable release.** - Given a directory of Swift files, -`swift-doc` generates CommonMark (Markdown) 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. -For an example of generated documentation, -[check out the Wiki for our fork of Alamofire][alamofire wiki]. +**Example Output** -> **Note**: -> Output is currently limited to CommonMark, -> but the plan is to support HTML and other formats as well. +- [HTML][swiftsemantics html] +- [CommonMark / GitHub Wiki][alamofire wiki] ## Requirements @@ -54,9 +49,9 @@ collecting all Swift files into a single "module" and generating documentation accordingly. ```terminal -$ swift doc generate path/to/SwiftProject/Sources --output Documentation -$ tree Documentation -$ Documentation/ +$ swift doc generate path/to/SwiftProject/Sources +$ tree .build/documentation +$ documentation/ ├── Home ├── (...) ├── _Footer.md @@ -64,8 +59,16 @@ $ Documentation/ ``` By default, -output files are written to `.build/documentation`, -but you can change that with the `--output` option flag. +output files are written to `.build/documentation` +in CommonMark / GitHub Wiki format, +but you can change that with the `--output` and `--format` option flags. + +```terminal +$ swift doc generate path/to/SwiftProject/Sources --output Documentation --format html +$ Documentation/ +├── (...) +└── index.html +``` #### swift-doc coverage @@ -178,114 +181,9 @@ jobs: with: path: "Documentation" env: - GITHUB_PERSONAL_ACCESS_TOKEN: ${{ secrets.GITHUB_PERSONAL_ACCESS_TOKEN }} -``` - -* * * - -## Motivation - -From its earliest days, -Swift has been fortunate to have [Jazzy][jazzy], -which is a fantastic tool for generating documentation -for both Swift and Objective-C projects. -Over time, however, -the way we write Swift code — -and indeed the language itself — -has evolved to incorporate patterns and features -that are difficult to understand using -the same documentation standards that served us well for Objective-C. - -Whereas in Objective-C, -you could get a complete view of a type's functionality from its class hierarchy, -Swift code today tends to layer and distribute functionality across -[a network of types][swift number protocols diagram]. -While adopting a -[protocol-oriented paradigm][protocol-oriented programming] -can make Swift easier and more expressive to write, -it can also make Swift code more difficult to understand. - -Our primary goal for `swift-doc` -is to make Swift documentation more useful -by surfacing the information you need to understand how an API works -and presenting it in a way that can be easily searched and accessed. -We want developers to be empowered to use Swift packages to their full extent, -without being reliant on (often outdated) blog posts or Stack Overflow threads. -We want documentation coverage to become as important as test coverage: -a valuable metric for code quality, -and an expected part of first-rate open source projects. - -Jazzy styles itself after Apple's official documentation circa 2014 -(code-named "Jazz", as it were), -which was well-suited to understanding Swift code as we wrote it back then -when it was more similar to Objective-C. -But this design is less capable of documenting the behavior of -generically-constrained types, -default implementations, -[dynamic member lookup][se-0195], -[property wrappers][se-o258], or -[function builders][se-xxxx]. -(Alas, -Apple's [most recent take][apple documentation] on reference documentation -hasn't improved matters, -having instead focused on perceived cosmetic issues.) - -Without much in the way of strong design guidance, -we're not entirely sure what Swift documentation _should_ look like. -But we do think plain text is a good place to start. -We look forward to -soliciting feedback and ideas from everyone -so that we can identify those needs -and figure out the best ways to meet them. - -In the meantime, -we've set ourselves up for success -by investing in the kind of foundation we'll need -to build whatever we decide best solves the problems at hand. -`swift-doc` is built on top of a constellation of projects -that take advantage of modern infrastructure and tooling: - -- [SwiftSemantics][swiftsemantics]: - Parses Swift code into its constituent declarations - using [SwiftSyntax][swiftsyntax] -- [SwiftMarkup][swiftmarkup]: - Parses Swift documentation comments into structured entities - using [CommonMark][commonmark] -- [github-wiki-publish-action][github-wiki-publish-action]: - Publishes the contents of a directory to your project's wiki - -These new technologies have already yielded some promising results. -`swift-doc` is built in Swift, -and can be installed on both macOS and Linux as a small, standalone binary. -Because it relies only on a syntactic reading of Swift source code, -without needing code first to be compiled, -`swift-doc` is quite fast. -As a baseline, -compare its performance to Jazzy -when generating documentation for [SwiftSemantics][swiftsemantics]: - -```terminal -$ cd SwiftSemantics - -$ time swift-doc Sources - 0.21 real 0.16 user 0.02 sys - -$ time jazzy # fresh build -jam out ♪♫ to your fresh new docs in `docs` - 67.36 real 98.76 user 8.89 sys - - -$ time jazzy # with build cache -jam out ♪♫ to your fresh new docs in `docs` - 17.70 real 2.17 user 0.88 sys + GH_PERSONAL_ACCESS_TOKEN: ${{ secrets.GH_PERSONAL_ACCESS_TOKEN }} ``` -Of course, -some of that is simply Jazzy doing more, -generating HTML, CSS, and a search index instead of just text. -Compare its [generated HTML output][jazzy swiftsemantics] -to [a GitHub wiki generated with `swift-doc`][swift-doc swiftsemantics]. - ## License MIT @@ -297,6 +195,7 @@ Mattt ([@mattt](https://twitter.com/mattt)) [ci badge]: https://github.com/SwiftDocOrg/swift-doc/workflows/CI/badge.svg [alamofire wiki]: https://github.com/SwiftDocOrg/Alamofire/wiki +[swiftsemantics html]: https://swift-doc-preview.netlify.app [github wiki]: https://help.github.com/en/github/building-a-strong-community/about-wikis [github actions]: https://github.com/features/actions [swiftsyntax]: https://github.com/apple/swift-syntax