[IDEA] Convert "Swift Programming Language Book" to docc and make it part of the website

The "Swift Programming Language Book" is currently available as a (i think custom built) website and e-pub. However, recent advances in DocC also provide a capable toolchain to build documentation pages. Therefore I propose to

  • Convert the "Swift Programming Language Book" to a DocC based codebase.
  • Open source it as a part of the swift website or a seperate repository (The license is already CC-BY-4.0 )
  • Publish the DocC based documentation as a part of the Swift Website.

IMHO this approach has several advantages

  • Consistency across the ecosystem: The Swift Book have a consistent look and feel aligned with other swift documentation.
  • Involvement of the community: Everyone will be able to contribute to the Swift Book.
  • Promote the usage for DocC.

As a proof of concept, i wrote a converter for the ePub Swift Book to DocC GitHub - fourplusone/swift-book-converter which certainly has some rough edges but shows the general idea

Link to generated documentation: Documentation

I'm curious about your opinion

18 Likes

This is really impressive! And agreed, making "The Swift Programming Language" book open source is a great idea.

The team inside Apple that has written and maintained the book so far, including sample code inlined within the book, is actively working to make the book itself open source using Swift-DocC. They are converting from today's custom tooling to standard DocC-compatible Markdown files, so it will be easier for the community to build and maintain in the open. Support for ePub is also an interesting area for future investigation.

They should have more to show for this work soon, and would be really interesting to see where the work you've already done can be applied.

13 Likes