Clearly indicate when a build resulted in no pages

[d-ronnqvist]

Clearly indicate when a build resulted in no pages

[d-ronnqvist]

This is kind of a good first issue. The coding changes are fairly small but there's a good opportunity here for a developer to think about the tradeoffs between various solutions and have a discussion in the Swift Forums to find the right solution.

Discussing the tradeoffs in the Swift Forums will require a new developer to familiarize themselves with behaviors of docc convert and docc preview.

[sofiaromorales]

Hi @d-ronnqvist, I would like to work on this. Since this issue is quite old, do you now if there's been any work or discussion related to it that I should be aware of?

[d-ronnqvist]

Hi. as far as I’m aware there has been no further work or discussion on this issue.

[d-ronnqvist]

There are a couple of different places where you could check if the build doesn't result in any pages.

The only place that I'm aware of that checks this today is in PreviewAction.printPreviewAddresses(base:) which prints the base preview paths of all the top-level pages (module pages, technology roots, and tutorials). The preview actions gets these paths from the documentation context as

previewPaths = try convertAction.context.previewPaths()

which in turn checks the context's rootModules and rootTechnologies. This works because individual symbols and articles only get a page if they belong to some module or technology.

We wouldn't want to tie this diagnostic to the code that prints the preview addresses but the underlying check could be the same.

One thing to consider is that the preview action internally uses a convert action, so if the two should behave differently then the convert action likely needs some new configuration that the preview action can control.

[sofiaromorales]

Hi @d-ronnqvist. I agree that this solution could use a combination of the different options you listed. My most immediate proposition when either previewing or converting documentation that will end up with no pages is to raise a warning, and, in the case of docc convert, not emit a doccarchive for those documentations that resulted in no pages. So a combination of solutions 1 and 2. This can also be discussed on the forums with the rest of the community. I’ll open a discussion there to talk about this.

In the meantime, could you point me to the files inside Swift-DocC that I should keep an eye on for this implementation? My best guess is that I have to check that the topic dictionary inside renderContext.store has data in it.

// DocumentationConverter.swift
mutating public func convert<OutputConsumer: ConvertOutputConsumer>(
        outputConsumer: OutputConsumer
    ) throws -> (analysisProblems: [Problem], conversionProblems: [Problem]) {
        ...
        // Precompute the render context
        let renderContext = RenderContext(documentationContext: context, bundle: bundle)

       // Emit warning if renderContext.store.topics is empty
       ...
}