First impression: Invalid or missing HTML template directory

Development Swift-DocC
1

Hi, I found out that the first-time experience, after fetching the docc repository and trying to use it is somehow confusing.

clone swift-docc
clone swift-book

and the first experience is: it doesn't work, and it doesn't say where to look for help

> swift run docc preview /path/to/swift-docc/TSPL.docc

Building for debugging...
Build complete! (0.44s)
warning: Invalid or missing HTML template directory
Invalid or missing HTML template directory, relative to the docc executable, at: '/Users/marcinkrzyzanowski/Devel/swift-docc/.build/arm64-apple-macosx/share/docc/render'.
Set the 'DOCC_HTML_DIR' environment variable to use a custom HTML template.

Conversion will continue, but the produced DocC archive will not be compatible with static hosting environments.

Pass the '--no-transform-for-static-hosting' flag to silence this warning.
Error: Invalid or missing HTML template directory, relative to the docc executable, at: '/Users/marcinkrzyzanowski/Devel/swift-docc/.build/arm64-apple-macosx/share/docc/render'.
Set the 'DOCC_HTML_DIR' environment variable to use a custom HTML template.
Usage: docc convert preview [<options>] [<source-bundle-path>]
  See 'docc convert preview --help' for more information.

Is the default template something I should provide by myself? I can't find anything about it in the documentation. Please point me out if it's described.

I'm not the only one confused here, apparently: swift - Unable to build documentaion using docc preview FILE.docc - Stack Overflow

I found that Xcode provides a template in /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/share/docc/render. I presume that is a template from GitHub - apple/swift-docc-render-artifact: Pre-built copy of the web renderer for Swift-DocC documentation.. If that's true, I see it as a documentation issue that it's not clear why it fails and what to do to make it work.

eventually, I figured that this command is what's expected:

DOCC_HTML_DIR=../swift-docc-render-artifact/dist swift run docc preview /Users/marcinkrzyzanowski/Devel/swift-book/TSPL.docc
1 Like
2

When I first looked into using DocC, I ran into this too. I searched for the error message in the source and saw that it was expecting the template to be at a particular path relative to the the docc executable. I knew there is no way to make SwiftPM install such a thing, so I deduced that DocC is not intended to be used apart from the toolchain. Perusing the plugin’s source provided corroboration. I was disappointed, because DocC had seemed to bill itself as a standalone tool (independently usable like swift-format). In the end, I only use it straight from the toolchain with $ xcrun docc and I abandoned the idea of contributing back to it.

3

The template configuration is briefly described in the CONTRIBUTING.md file, but I agree that it probably deserves to be called out in the README.md at least and possibly made more clear.

Thanks for sharing your initial impressions. Hopefully we can improve this experience for everyone.

2 Likes