Consider using Cocoadocs to generate/host docs.

[wearhere]

Pros

• Cocoadocs renders the index for us. Doing this ourselves is a tremendous pain.
  • Counterargument: it was a huge pain but now it's done.
• Cocoadocs hosts older versions of the documentation.
  • Counterargument: installing old versions of the docs locally works (with an old version of Subliminal checked out, you just run rake install and we download the appropriate version of the docs--we host the old xar files on the gh-pages branch). We could probably come up with a scheme to expose older versions of the HTML through our GitHub site too if we wanted.
• Cocoadocs features links to install the docs in Xcode and Dash.
  • Counterargument: rake install already does this for us. (However, Dash does make it very easy to download specific versions of the docset.)
• Cocoadocs puts nifty "search for examples in GitHub" links next to class names. (Example)
  • Counterargument: We could do this too if we wanted.
• Cocoadocs users know exactly where to find our docs.
  • Counterargument: This might not be an issue depending on how the spec's documentation_url (pointing to us) is featured by Cocoadocs (although I'd be surprised if Cocoadocs propagated it through their search API and into Dash).

Cons

• We cede control over the precise formatting of the documentation. Cocoadocs has signalled numerous times that they don't want to let projects specify custom arguments to Appledoc.
  • Counterargument: Cocoadocs might be amenable to customization at a higher level than Appledoc arguments.
• We lose the ability to suppress Appledoc warnings to work around Appledoc bugs (e.g. false invalid crossrefs), for the same reason as the last point.
  • Counterargument: Same as above. It would also be in everyone's interest for these bugs to be fixed.
• We would still need to generate the docs ourselves as part of CI, to guarantee project integrity; and it would be impossible to guarantee that we built the docs in the exact same way as Cocoadocs.
  • Counterargument: we could use the same Appledoc script as Cocoadocs, and whatever formatting we couldn't replicate might not be absolutely crucial to the integrity of the docs.

[MaxGabriel]

So I'm a little unclear on if Cocoadocs is supposed to be generating docs for Subliminal right now. Their README says you can use the documentation_url attribute, but they generate documentation for libraries that use that anyway.

Edit: The README is now working on the Cocoadocs version of Subliminal's docs.

One advantage of using Cocoadocs is that there's active design working going into it (see their current issue list).

[MaxGabriel]

Cocoadocs announced a new design/some new features today. Here's how Subliminal's docs would look in the new design, assuming default configuration: http://maxgabriel.github.io/SubliminalDocs/

[wearhere]

I agree it's curious that Cocoadocs is generating docs for Subliminal despite our use of the documentation_url attribute. If they do generate documentation that's kinda the best of both worlds, because then the docset is discoverable through Dash.

Nevertheless, I'm leaning toward adopting Cocoadocs--so that there's one true source of documentation; to simplify Subliminal's installation and build process; and to benefit from Cocoadocs' design work. Two things would need to happen for us to do that, though:

1. We'd need to be able to customize the invocation of appledoc, to add the following flags:

   • --keep-merged-sections: Ensures that the @name sections in categories show up in the class documentation when the categories are merged to the classes, rather than all the methods in the categories being merged under a single section whose name is that of the category.
   • --no-repeat-first-par: Don't repeat the first paragraph of the member documentation.
   • --no-warn-invalid-crossref: Don't warn on invalid cross references (as Appledoc considers cross references to system classes).

   These flags make documentation better-structured IMO and I wouldn't want to give them up. But perhaps the Cocoadocs team would be open to setting them as defaults--the existing settings seem slightly arbitrary and it's admittedly unclear what some of Appledoc's setttings do unless you read the source.

   If the Cocoadocs team doesn't want to change the defaults, perhaps we can add options to .cocoadocs.yml.

2. bundle exec ./cocoadocs.rb preview Subliminal (or some similar command) would need to output warnings, so that we could use it to test-build the docs in CI as we do currently. (Perhaps it does output warnings already, I don't know. Xcode format would be nicest, like we use currently).

[wearhere]

Ok, I think that we should do this. Appledoc appears likely to fall behind https://github.com/realm/jazzy sooner rather than later, considering it stopped compiling in Xcode 5.1, doesn't support Swift, and its documentation is still down; and the version which will address these issues is just getting off the ground.

Of course, jazzy isn't at all stable either currently, but I'd rather let Cocoadocs track this and make the migration--which they've signaled they're going to do.

#71 should be resolved one way or the other before tackling this, but only so that we're "completely" documented before switching over (and may discover additional inconsistencies we'd want Cocoadocs to address á la the list above).