[SR-15576] [Swift-DocC] Transform-for-static-hosting does not DocC's experimental custom header/footer feature

[apple]

[SR-15576] [Swift-DocC] Transform-for-static-hosting does not DocC's experimental custom header/footer feature

[ethan-kusters]

@swift-ci create

[ethan-kusters]

We'll use this bug to track support specifically for `docc convert --transform-for-static-hosting --enable-experimental-custom-templates`.

Support for `docc archive transform-for-static-hosting --enable-experimental-custom-templates` is tracked separately with SR-15750.

[ethan-kusters]

I think this would be a good starter issue. Here's some thoughts on how to get started:

DocC's transform for static hosting logic for docc convert follows this general code path:

1. ConvertAction.swift#L319: Check if a copy of Swift-DocC Render has been provided and find the URL for the index.html it contains. If the user has provided a custom hosting base path, use the template-index.html and do some string replacement to write out a custom index.html and save that URL. Primary goal of this section is to get the URL for the index.html file that needs to be copied around for static hosting.
2. ConvertAction.swift#L372: Pass that index.html URL to the convert action's file writer.
3. ConvertAction.swift#L378: Begin the conversion process.
4. DocumentationConverter.swift#L293: Documentation converter converts an individual render node and passes it to the file writing consumer.
5. ConvertFileWritingConsumer.swift#L61: File writing consumer passes the render node to the render node writer.
6. JSONEncodingRenderNodeWriter.swift#L120: The render node writer creates a copy of the index.html in the currently building DocC archive (provided by step (2)) to a path relative to where the current render node being written in the data directory.

Separately, in ConvertFileWritingConsumer there's logic that picks up any provided custom header/footer templates and injects them in to that same index.html at the root of the DocC archive: ConvertFileWritingConsumer.swift#L191.

Unfortunately, the ConvertFileWritingConsumer is provided the custom header/footer templates after it's already written out all of the render nodes, and thus copied around the index.html without the injected header/footer.

• DocumentationConverter.swift#L293: Documentation converter converts an individual render node and passes it to the file writing consumer.
• DocumentationConverter.swift#L333: Documentation converter passes all of the bundle's assets (including the custom header/footer templates) to the file writing consumer.

And so we end up in the situation where the index.html file at the root of the emitted archive has the correctly injected custom header/footer, but all of the other index.html files for each individual render node are incorrect.

---

I believe the simplest fix here would be to just move the call to try outputConsumer.consume(assetsInBundle: bundle) in DocumentationConverter before any calls to try outputConsumer.consume(renderNode: renderNode). This would ensure that whenever the output consumer consumers a render node, the index.html in the output archive is the correct, already transformed one.

An alternative solution would be to move the logic for injecting custom header/footer earlier in the process.

Either way, we'll need to add a test that ensures that when a bundle that includes a custom header/footer is converted with support for static hosting, that custom header/footer is included in all of the copied index.html files. For that, I would create new copy of testConvertWithCustomTemplates() that converts a bundle the includes actual content (that can be done by adding a symbol graph to the folder used as input). Then assert that the each of the copied index.html files also have the expected content just as the current test is asserting that the one at the root does.

[mportiz08]

@ethan-kusters can this be closed with the merge of #410?

[ethan-kusters]

@mportiz08 Yes! Thank you for the ping.