Update README.md

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,18 +49,26 @@ 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
 └── _Sidebar.md
 ```
 
 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