Rearchitect documentation generators

[mattt]

One of the consequences of #65 is that we now have an option that applies to HTML output, but not CommonMark. This kind of divergence isn't unexpected — certainly, as we expand functionality to support additional output formats like DocSets (#27), it was inevitable.

We're at the point now where the original assumptions we made to ship the initial proof-of-concept are starting to break down, and it'd be great to find a solution that will set us up for success in version 1.x and beyond.

Here's what I'm looking for in a solution, in order of importance:

1. Something that lets us add support for new formats, without encroaching on or breaking the existing ones.
2. The ability to test generated output without actually running the swift-doc command (a full integration test should be run separately), as discussed in #62
3. The ability for users to use a 3rd-party generator without forking swift-doc itself — for extensibility, but also some flexibility for us about what's included in the main offering.

...so basically, a plugin system. 😭

So far, the only solution I've been able to come up with that meets all three of these criteria is to make each format its own subcommand of generate. For example, running:

$ swift doc generate html

...would look for an executable named swift-doc-generate-html. This is the same approach that allows swift-doc to be executed as a subcommand of swift, and would let anyone write and/or install their own custom output format.

Does anyone else have any other ideas about what we should do?

[muizidn]

Would love to see and help implement this feature even if first iteration isn't optimal yet. My use case for now is I need a PDF generator which allow me to send fully cross referenced PDF document to the interested client.

Anything I can start from @mattt?

[mattt]

@muizidn I wouldn't consider PDF to be a primary output format for swift-doc. Instead, I'd recommend using a tool like PrinceXML to generate PDF from HTML + CSS.

[muizidn]

Ah sure. Thanks your reply.