From what I understand, by default, all types (enums, structs, etc.) are shown in the root documentation page... unless they are specifically mentioned in some Markdown file inside the docc archive. We like how this lets us organize our documentation into sections and nested files.
Is there a way to check (in CI, so programmatically) whether there are unmentioned symbols in the archive? As in, whether there are any symbols being shown in the root of our documentation below our carefuly curated categories? Right now, I have to manually check this for every merge request as I haven't found any way to automate the process.
You've understood correctly that DocC provides a default organization for symbols and articles when the content doesn't specify an explicit organization for that page. I'm not aware of a good way to check what pages are explicitly organized and what pages are automatically given a default organization.
DocC has an experimental feature for reporting "documentation coverage" and I feel like this topic (documentation organization) could be good to discuss in that context. My thinking is that the use case for wanting to know if there are symbols (or other pages) with default organization is somewhat similar to the use case of wanting to now if there are symbols without documentation (or with partial documentation).
I've used the experimental coverage features for exactly this functionality. The downside is that it's not always obvious, but if you know the numbers to look for, they can be helpful. As an example from one of my libraries:
The "abstract" percentage for types and members is all about the one-line descriptions for each type, and the curated percentage is what's been organized. If one of those curated numbers drops, then I've likely added a symbol in the code, but haven't "placed it" in the organization.
Be aware though - it's experimental (as @ronnqvist mentioned), and I've seen far more issues with it trapping out and failing when I use it with libraries that have deeper dependency trees, and that's particularly noticeable in a CI-like situation, so I'd be very wary of recommending this kind of thing as a "check" for a PR - although it's been helpful in a purely "advisory" role for me.
@ronnqvist A relevant question to this thread: is there a way to hide the types that aren't mentioned in the custom topic groups on the landing page?
Our framework is quite large and has thousands of types. We don't want to congest the landing page with all the types, only want to display the most relevant ones. Thanks!
No, by design every symbol appear in the documentation hierarchy (at least) once. This closely relates to another DocC principle that the documentation matches the API 1:1.
If you have a handful of types that you know are more relevant and organize those types into topics on the framework's page, then those topics will appear above any automatic organization, making them the first things that other developers see when they read the documentation for your framework.
Alternatively, if each topic is a bit larger and could benefit from its own conceptual documentation then you can write an article for each topic and curate the relevant symbols there. Then on the framework page you would organize all the articles into one or more topic sections (which shows then above the automatic topic sections). We use this approach for the Swift-DocC framework documentation (source, hosted) and its sub pages (source, hosted).