swift-doc

swift-doc copied to clipboard

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?

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?

@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.

Ah sure. Thanks your reply.