I've got a bunch of code written in CG-SQL. I'd like to document it. The CG-SQL compiler already spits out a bunch of metadata about all the functions and procedures.
What's currently needed in order to allow DocC to support another language? Is there an interim representation that I can output as part of my build process, which DocC can read in order to generate the actual pages?
The DocC flow today works with refining out content for symbols from the compiler in a symbolgraph, represented by the library swift-docc-symbolkit, after which DocC itself transforms that into JSON data structures expected for rendering the content with the DocC renderer.
I don't know the SQLsite stored proc language, but I expect it would map in a fairly straightforward way into the concepts already in SymbolKit, which most of the time is represented in a JSON data structure. That would be the "big lift" part of something like this in my mind, or at least where I'd start. Do the work to extract/generate a symbolgraph from the CG-SQL, then hand that off to DocC and see how it does when it's interpreted/rendered through that lens.
There's a bit of exploring of this exact process recently for refining the JSON data dump from Swift Argument Parser arguments, although nothing terribly solid to base your work from, and there's similar work I think reflected in the GSOC project to map OpenAPI concepts into a symbolgraph. That might be worth looking at, as it's investigating the space as well.
I can certainly have a go at that! Once I've got the data in symbolgraph format, is there any docs on how to pipe that into DocC?
The easiest would be to add the symbol graph files to the documentation catalog (directory with a '.docc' extension) that you pass to docc convert.
I thought that the documentation mentioned this but AFAICT there's no mentions of symbol graph files at all. The top-level page of the SwiftDocC framework documentation mention that documentation catalogs can contain symbol graph files but we don't expect end users who interact with the docc executable to read (or find) that documentation.
Following up on @ronnqvist's advice - symbol graphs are output by the swift compiler for Swift, and the Swift DocC plugin does the pertinent orchestration for swift packages/libraries so that you don't have to fiddle with it when generating documentation. The underlying docc driver command takes one or more of them, along with the catalog location, when it's making the DocC archive - and I'd agree is the easiest place to start.
If you want to explore some existing symbolgraphs, you can dump them out from a swift project using the command: swift symbolgraph-extract, although there's also ways of getting the raw details straight from the C compiler. There was a forum thread about which to use a few months back.
The structure of a symbolgraph isn't strongly documented - is generally JSON, and the swift library that models it is GitHub - swiftlang/swift-docc-symbolkit: A Swift package for encoding and decoding Swift Symbol Graph files. - and there's documentation for it on GitHub pages from that repo : https://swiftlang.github.io/swift-docc-symbolkit/documentation/symbolkit/
Those docs, particularly Documentation and below, highlight the properties and hint as to how they're expected to interact.