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
│ ├── CollectionTypes_intro~dark@2x.png
├── 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.
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