I'm looking to show docc generated output in an iOS app, but whatever I do I only see blank pages when loading a local instance of the generated index.html in a WKWebView.
I've tried generating the static HTML using xcrun docc process-archive transform-for-static-hosting but that hasn't seemed to help and no matter what path I try to select, it always shows up as blank).
Any tips for including docc in a local iOS project for viewing?
I've not tried this specific trick myself, so take any advice/feedback as such - the trick will be getting the single page app that is the DocC renderer kicked up and passed a correct URL. If you weren't aware, the content that is generated by DocC isn't a dump of static HTML content, but a collection of JSON blobs that represent all the information and a Vue.js javascript app to present it.
It's the same issue as generating the content locally and then opening up the index.html in that directory - it's also going to show you the blank page. The URL that it's expecting to see is /documentation/{your_package_name}/.
(For example, I have a library CRDT, and when I render it for static hosting - and push it up to GitHub, the URL it'll used to be shown at is https://heckj.github.io/CRDT/documentation/CRDT
(Note: that example URL isn't active, just illustrative - These days I host my docs on the Swift Package Index - so the content lives at CRDT Documentation – Swift Package Index)
Hm. It's hard to know exactly what might be going wrong, especially if you've already tried using the static html output with the correct URLs.
One thing that might be helpful to debug the issue is enabling the web inspector so that you can see if there are any network errors or JavaScript crashes happening. It sounds like there is a property on the WKWebView that you can toggle to enable the inspector for debugging purposes: isInspectable | Apple Developer Documentation
Hope that helps!
And another thought that comes to mind is that you will most likely need some sort of basic http static file server that is delivering the actual content. As @Joseph_Heck mentioned, it is likely the same issue you would have trying to open the HTML file directly in Safari, which unfortunately won't just work today.
Thanks @Joseph_Heck @marcus_ortiz. I was able to get it working after adding a webserver to the app.
Alternatively, would it be possible to build a modified version of the built-in Xcode Documentation Viewer? That doesn't appear to be using a web view.
Is there an option to avoid the web viewer entirely like the Xcode Documentation viewer?
It's a whole lot of rendering, but all the data that goes into it is in that docc directory (looking under data and you'll see a JSON file for every symbol).
@Helge_Hess1 has an article (and related code) that was generating static HTML from earlier versions of the Docc catalog files as static HTML (under DocZ · GitHub). Within that repo the part that's probably critically useful for this task would be the library GitHub - DoccZz/DocCArchive: Swift package to read and process "DocC" archives, which is pretty up to date - although I don't know if there are changes in the Swift6 updates that it doesn't have incorporated. It's basically a parsing library for the docc JSON data structures.
(I haven't used it myself, although I explored pushing the doczz code a bit farther forward at one point - just didn't have sufficient need to drive me to trying to update it and deal with the edge cases that don't translate well to static HTML)
To be clear, is the assumption (or maybe we know for sure?) that the built in viewer in Xcode is using the json to create native UI and skipping the html/js entirely?
The viewer does seem to be non-html, especially the navigation on the left. Ultimately I’m looking to create something similar to the built in viewer, but with some extra functionality.
If you use the Accessibility Inspector, you’ll find that the documentation viewer, Quick Help, and option+click popover all render web content. So you’ll probably want to start with a fork of the swift-docc-render repository where you override the data loading logic to pull the JSON from somewhere other than the local server (such as by putting all the JSON into a global variable, or using a WKSciptMessageHandler to read the files on demand). Then you can customize the web app as desired (for example, by removing the sidebar navigation and vending the underlying data model for that back to native UI to render your own navigation)
Interesting.
Is the documentation viewer a hybrid of native and web then? The navigation appears native given the formatting of the side menu, filters, top navigation, and search bar and the individual files render web content.
If that's the case, is any of that native navigation open source or would that have to be custom built?
I don’t believe any of the UI parts of Xcode are open source.
DocZ btw also has the server parts to host the dynamic pages from the official site builder: GitHub - DoccZz/servedocc: A small Swift tool/server to serve DocC archives to your browser (it is very simple and could be easily embedded in an app).
If I'd build an app to display the content, I'd probably go for DocCArchive to read the contents of a catalog. Not sure whether I would use HTML (generated from within the app) or not for content display, might make sense.
Thanks! I just imported DocCArchive and am exploring how it works.
Looks like I could use that to build out the navigation sidebar.
Are you suggesting using DocCArchive to make a custom renderer using native components via the json and avoid the html/javascript altogether?
DocCArchive may need some additions for newer properties, but that's not hard, you can checkout other PRs on how that was done before.
I would try to avoid the JavaScript altogether, but might still be rendering HTML for display, similar to what my docc2html does (not very well, but it is a starting point).
Maybe a combination of HTML and native. Like the core content as HTML, but surrounding things like title and navigation could be say SwiftUI.
Depends a little on what the goal is. Regular documentation content should be pretty straight forward, but interactive tutorials might be hard to get working w/o the official JS stuff.
Thanks!
Ultimately the goal is to have an app similar to the native documentation viewer, which also allows injecting native components. I have that part working - showing native components in a WKWebView.
The web version of documentation navigation isn't as nice as the native Xcode viewer though, so I'd love to potentially use DocCArchive for laying out the navigation (sidebar) and then can use the HTML for rendering.
The only other part that isn't entirely clear would be hooking up the HTML links to the native navigation.
Thanks again for all the thoughts/tips.