Unable to build documentaion using docc preview FILE.docc

Question

While working with a Swift Documentation file, when I run docc preview FILE.docc, the console shows an error:

zsh: command not found: docc

Which I know why as docc binary is not available in my documentation workspace. So I cloned the docC repo, build it, and moved the binary to a universally available location, and now when I run it, I get:

Building for debugging...
Build complete! (0.53s)
Error: Invalid or missing HTML template directory, relative to the docc executable, at: '/Users/johnekoreh/Desktop/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.

The FILE.docc is a clone of https://github.com/apple/swift-book from GitHub, and I am trying to run it locally...

While the tree structure of FILE.docc is:

├── Assets
│   ├── CollectionTypes_intro_2x.png
│   ├── [email protected]
├── GuidedTour
│   ├── AboutSwift.md
│   ├── Compatibility.md
│   └── GuidedTour.md
├── Info.plist
├── LanguageGuide
│   ├── AccessControl.md
│   ├── AdvancedOperators.md
│   ├── AutomaticReferenceCounting.md
│   ├── BasicOperators.md
│   ├── ClassesAndStructures.md
│   ├── Closures.md
│   ├── CollectionTypes.md
│   ├── Concurrency.md
│   ├── ControlFlow.md
│   ├── Deinitialization.md
│   ├── Enumerations.md
│   ├── ErrorHandling.md
│   ├── Extensions.md
│   ├── Functions.md
│   ├── Generics.md
│   ├── Inheritance.md
│   ├── Initialization.md
│   ├── Macros.md
│   ├── MemorySafety.md
│   ├── Methods.md
│   ├── NestedTypes.md
│   ├── OpaqueTypes.md
│   ├── OptionalChaining.md
│   ├── Properties.md
│   ├── Protocols.md
│   ├── StringsAndCharacters.md
│   ├── Subscripts.md
│   ├── TheBasics.md
│   └── TypeCasting.md
├── ReferenceManual
│   ├── AboutTheLanguageReference.md
│   ├── Attributes.md
│   ├── Declarations.md
│   ├── Expressions.md
│   ├── GenericParametersAndArguments.md
│   ├── LexicalStructure.md
│   ├── Patterns.md
│   ├── Statements.md
│   ├── SummaryOfTheGrammar.md
│   └── Types.md
├── RevisionHistory
│   └── RevisionHistory.md
├── The-Swift-Programming-Language.md
├── footer.html
├── header-publish.html
└── header-staging.html

I am not getting how to get around the missing HTML template directory error as I can't build the FILE.docc with swift run build as it is not a package and there seems to be no other option to build it as an HTML project.

Tried building it using the docc preview FILE.docc command and expected to see a success message about running the documentation on localhost.

Answer 1

DocC does not provide a "template" on its own. It expects it installed at a certain path, that you don't have.

To solve that, you need to fetch the template and provide a path to it. Default template is available at https://github.com/apple/swift-docc-render-artifact

Fetch it

git clone https://github.com/apple/swift-docc-render-artifact

set DOCC_HTML_DIR to swift-docc-render-artifact/dist, for example

DOCC_HTML_DIR=/path/to/swift-docc-render-artifact/dist swift run docc preview FILE.docc

other than that, there's docc that comes with Xcode, it's fully setup. You can call it with

xcrun docc preview FILE.docc

good luck