I have seen some apple documentation that document configuration options that can be added to plist, this one for example. The formatting of these documentation matches documenting other symbols with icons according to the type of configuration option.
I am providing some configuration options to a build tool plugin as part of my MetaCodable library and want to document those options. Is there any way I can achieve the same behaviour?
Hi Soumya -
I'm not sure I understood your question - is the heart of it something along the lines of "I have some configuration for my library that I store/use from a plist format. How can I get that documented, with some attempt at mirroring the way it's laid out in Apple's documentation?"
If so, I suspect the most expedient path would be to create pages that are the equivalent of articles for each Plist entry, matching the format by specifying things a bit manually. The reason is that underneath the covers, DocC works from a JSON symbol-graph that's exported from CLANG, with the primary set being what's provided out of Swift. When the DocC team added Objective-C support, they added a concept of "variants" to this data model - but at the heart of things, the symbol graphs are fundamentally information about classes, structs, functions, etc. (You can dig around in the data model looking in the project SymbolKit)
You could assuredly do something to convert your own Plists into a symbol graph, add them to the set used by DocC, but that flow going to be shimming in to some "weird spots" such that you'll need to know quite a bit about how the overall flow of things within DocC and it's conversion process work.
I suspect Apple has something that does a custom graph implementation from Plist (and the same with converting OpenAPI schema, based on their web framework documentation) - but those tools (to my knowledge) aren't publicly available.
Hi Joseph,
Thanks for replying, To clarify, I have a build tool plugin that user can include in their targets. This build tool provides some customisation options that user can take advantage of by including a plist/json file in their target and providing these options. I want to document these options same as Apple has done.
I will have a look on SymbolKit if I can have what I want without the manual approach.
Thanks @Joseph_Heck for guiding me in the right direction, I have created some documentation for custom configurations by creating custom symbol graph:
However, the challenge I face now is giving this a separate icon than other Swift symbols similar to what apple does. The only thing I see is using identifier for kind which gives default icons for that symbol kind (You can find the custom symbol graph I created here).
Is there any way I can customize this?
I'm afraid that with DocC, you're quite restricted on that front - The renderer maps the kind of symbol to provide the icon, but there's no capability to provide you own or add custom displays along those lines (at least that I've seen)
In your place, I think I'd try to lean into whatever the closest metaphor was in the Swift type system. If you really wanted to push it, you could propose an expansion of SymbolGraph.Symbol.KindIdentifier that type system to explicitly support some new types that could be used for this kind of use case, but there's a lot of lifting to get some a new defined type all the way through to new default icons, and that may be more work than you'd want to tackle
In the documentation that you host on the web you can customize the icon in the navigator using a @PageImage directive with the icon purpose.
Thanks David!! Glad to know I was wrong
You are correct here, I initially tried this with Xcode's doc preview and abandoned it since it didn't work, but it does work for web hosting purposes.
