search

realm / jazzy

Soulful docs for Swift & Objective-C
https://realm.io
MIT License
7.35k stars 413 forks source link

Add support for ingesting DocC archives or JSON as input #1256

Open jpsim opened 3 years ago

jpsim commented 3 years ago

Instead of passing in a SourceKitten JSON file, jazzy could ingest a DocC archive or the JSON file(s) embedded within as input.

This could help users who've invested in custom themes or other jazzy features over the years get the benefits of using DocC as the documentation collection part of the pipeline.

I'm attaching the Yams DocC documentation archive as generated by Xcode 13 beta 1 which we can use as a reference. Yams.doccarchive.zip

The JSON files under data/documentation seem to have everything we currently get from SourceKitten. There seems to be a JSON file for every declaration included in the documentation, but it might be sufficient to just read the JSON file at the root (e.g. Yams.doccarchive/data/documentation/yams.json) I'm not sure yet.

Obviously with DocC being (currently) closed source and this JSON format likely being in flux and subject to change at any time, we probably can't rely on the exact format staying stable, but this can still be worthwhile even with that risk.

jpsim commented 3 years ago

cc @johnfairh

johnfairh commented 3 years ago

The top-level yams.json looks to have just the top-level contents, the directory structure below has the individual symbol data and hierarchy.

Although this is derived from symbolgraph json (that jazzy understands) it is heavily munged to exactly match the apple docs design (eg. markdown has been parsed and reserialized, extensions have been merged).

Probably the least painful approach for a jazzy importer is to go straight to the SourceDeclaration level without trying to make up the SourceKit structures, mainly because the extensions have already been sorted out and marked up.

It looks like they haven't yet decided what to do with extensions of types from other modules.

eneko commented 3 years ago

Maybe this is something that SourceKitten could handle, taking an input instead of parsing the code?

This would allow for any tools using SourceKitten, not just Jazzy, to take advantage of this feature.