Hello! I've been following along with DocC's development since it was announced publicly and I love so many things about it, thank you for making such a great tool for the technical writing community! I've been especially loving how easy it is to make interactive tutorials (Introducing Slipstream).
I saw that DocC-render is built in Vue.js, which I suspect is particularly helpful for some of the interactive aspects of the site (tutorials).
It's gotten me wondering though, especially as I've been working on Slipstream, whether DocC might be more accessible to the Apple dev community if the renderer were built in something closer to SwiftUI that would emit static HTML with less reliance on JavaScript as a nice side-effect.
Before I dive too deep into this though (my nerd-snipe senses are tingling on this one), I wanted to post the idea/question here and get a sense of whether I'm completely off the mark! Happy to poke at this with others and see if there's something here.
Looks like the starting place might be to manually generate the symbol graphs, which emits json files that I can then read into a Slipstream site generator: swift-docc/CONTRIBUTING.md at main · swiftlang/swift-docc · GitHub
What an enticing rabbit hole this is 
The symbol graph is a compiler output that reflects the available symbols in a package or framework target. If you want to handle DocC's output to convert it into something else, you'll probably want to inspect the Render JSON it outputs, as reflected by the RenderNode type and in the OpenAPI specification we maintain for it. This is what Swift-DocC-Render consumes to display a documentation site.
If you want to bypass Swift-DocC and generate documentation output yourself, you might also be interested in @taylorswift's swiftinit and swift-unidoc projects, which do this to host documentation infrastructure.
3 Likes
Thanks for sharing those links! @taylorswift: your projects are similarly rendering HTML it looks like; do you think something like Slipstream could make it easier to iterate on the generated HTML? Wondering if there's a way to consolidate all of these site renderers onto a common Swift-friendly community solution 
1 Like
Swiftinit itself is not a âstaticâ site, and it currently uses swift-dom to generate all of its HTML, almost all of which is dynamic.
Swiftinit can export static HTML through its rendering API, @tiborbodecs and @Joannis_Orlandos are currently using it to generate the swiftonserver.com site, although the export system is intended to be used for âlong formâ documentation like articles and tutorials rather than API references.
the external rendering system as it currently exists yields one HTML page at a time, as far as i am aware Tibor and Joannis are doing something extra to collate those pages into the swiftonserver website. they may (or may not) have a use for a tool that can assist with that.
1 Like
Actually, I have a static site generator written in Swift that can do the job. We integrate the rendered HTML content (generated by the SwiftInit service) into our build pipeline; thatâs how swiftonserver.com is made. The DocC articles are part of a separate repository, and we simply use the render API (mentioned above) to import the HTML along with some additional markdown content and YAML metadata to process everything. Feel free to take a look at our repository. The project is still a work in progress, but we are already looking for user feedback. :)
1 Like