generated docs only report: "An unknown error occurred."

[dastrobu]

Docs generated with swift-docc-plugin always result in a page showing only: An unknown error occurred. as can be seen on https://dastrobu.github.io/AccelerateArray/

The docs are generated without error or waring from the following steps:

/Users/runner/hostedtoolcache/swift-macOS/5.9/x64/usr/bin/swift --version
Apple Swift version 5.9 (swift-5.9-RELEASE)
Target: x86_64-apple-macosx12.0

swift package  --allow-writing-to-directory ./docs  generate-documentation  --output-path ./docs  --hosting-base-path AccelerateArray  --disable-indexing  --transform-for-static-hosting
  shell: /bin/bash -e {0}
  env:
    TOOLCHAINS: swift 5.9

Fetching https://github.com/apple/swift-docc-plugin
[1/1433] Fetching swift-docc-plugin
Fetched https://github.com/apple/swift-docc-plugin (1.22s)
Fetching https://github.com/apple/swift-docc-symbolkit
[1/2359] Fetching swift-docc-symbolkit
Fetched https://github.com/apple/swift-docc-symbolkit (1.18s)
Computing version for https://github.com/apple/swift-docc-symbolkit
Computed https://github.com/apple/swift-docc-symbolkit at 1.0.0 (0.72s)
Creating working copy for https://github.com/apple/swift-docc-symbolkit
Working copy of https://github.com/apple/swift-docc-symbolkit resolved at 1.0.0
Creating working copy for https://github.com/apple/swift-docc-plugin
Working copy of https://github.com/apple/swift-docc-plugin resolved at main
Building for debugging...
[1/39] Emitting module SymbolKit
[2/50] Compiling SymbolKit SourceOrigin.swift
[3/50] Compiling SymbolKit GenericConstraints.swift
[4/50] Compiling SymbolKit Swift.swift
[5/50] Compiling SymbolKit SemanticVersion.swift
[6/50] Compiling SymbolKit AccessControl.swift
[7/50] Compiling SymbolKit Availability.swift
[8/50] Compiling SymbolKit AvailabilityItem.swift
[9/50] Compiling SymbolKit Domain.swift
[10/50] Compiling SymbolKit DeclarationFragments.swift
[11/50] Compiling SymbolKit Fragment.swift
[12/50] Compiling SymbolKit FragmentKind.swift
[13/50] Compiling SymbolKit FunctionParameter.swift
[14/50] Compiling SymbolKit FunctionSignature.swift
[15/50] Compiling SymbolKit Identifier.swift
[16/50] Compiling SymbolKit KindIdentifier.swift
[17/50] Compiling SymbolKit Location.swift
[18/50] Compiling SymbolKit Mutability.swift
[19/50] Compiling SymbolKit Names.swift
[20/50] Compiling SymbolKit SPI.swift
[21/50] Compiling SymbolKit Snippet.swift
[22/50] Compiling SymbolKit Extension.swift
[23/50] Compiling SymbolKit GenericConstraint.swift
[24/50] Compiling SymbolKit Mixin+Equals.swift
[25/50] Compiling SymbolKit Mixin+Hash.swift
[26/50] Compiling SymbolKit Mixin.swift
[27/50] Compiling SymbolKit LineList.swift
[28/50] Compiling SymbolKit Position.swift
[29/50] Compiling SymbolKit SourceRange.swift
[30/50] Compiling SymbolKit Metadata.swift
[31/50] Compiling SymbolKit Module.swift
[32/50] Compiling SymbolKit OperatingSystem.swift
[33/50] Compiling SymbolKit Platform.swift
[34/50] Compiling SymbolKit Relationship.swift
[35/50] Compiling SymbolKit RelationshipKind.swift
[36/50] Compiling Snippets Snippet.swift
[37/50] Emitting module Snippets
[38/50] Compiling Snippets SnippetParser.swift
[39/50] Compiling SymbolKit GenericParameter.swift
[40/50] Compiling SymbolKit Generics.swift
[41/50] Compiling SymbolKit Namespace.swift
[42/50] Compiling SymbolKit Symbol.swift
[43/50] Compiling SymbolKit SymbolKind.swift
[44/50] Compiling SymbolKit SymbolGraph.swift
[45/50] Compiling SymbolKit GraphCollector.swift
[46/50] Compiling SymbolKit UnifiedSymbol+Encodable.swift
[47/50] Compiling SymbolKit UnifiedSymbol.swift
[48/50] Compiling SymbolKit UnifiedSymbolGraph+Encodable.swift
[49/50] Compiling SymbolKit UnifiedSymbolGraph.swift
[50/54] Compiling snippet_extract URL+Status.swift
[51/54] Compiling snippet_extract SymbolGraph+Snippet.swift
[52/54] Compiling snippet_extract SnippetBuildCommand.swift
[53/54] Emitting module snippet_extract
[53/54] Linking snippet-extract
Build complete! (32.64s)
Building for debugging...
[1/4] Compiling AccelerateArray internal.swift
[2/4] Compiling AccelerateArray cblas.swift
[3/4] Compiling AccelerateArray lapack.swift
[4/4] Emitting module AccelerateArray
[5/5] Compiling AccelerateArray vDSP.swift
Build complete! (29.06s)
Generating documentation for 'AccelerateArray'...
Converting documentation...
Conversion complete! (0.19s)
Generated DocC archive at '/Users/runner/work/AccelerateArray/AccelerateArray/docs'

What I am missing personally the most is a way to troubleshoot this error. Being also a web developer, I would like to be able to get unminifed javascript, showing what is actually going wrong or some flags to generated the web app with some console logs pointing me at what is going wrong.

Solving the issue with my package is just one thing. Enabling the docc plugin for better trouble shooting would be the long term goal.

Checklist

• [x] If possible, I've reproduced the issue using the main branch of this package.
• [x] This issue hasn't been addressed in an existing GitHub issue.

Expected behavior

It shows the same result as when running locally with

swift package --disable-sandbox preview-documentation

Actual behavior

shows: An unknown error occurred.

Generated docs can be found in: https://github.com/dastrobu/AccelerateArray/tree/gh-pages

Steps to Reproduce

1. clone or fork https://github.com/dastrobu/AccelerateArray
2. generate the docs as in https://github.com/dastrobu/AccelerateArray/blob/main/.github/workflows/docc.yaml
3. serve the docs from a GitHub page

Swift-DocC Plugin Version Information

Swift-DocC plugin version: 1.3.0 and main Swift Compiler version: Output from swiftc --version.

Apple Swift version 5.9 (swift-5.9-RELEASE)
Target: x86_64-apple-macosx12.0

see https://github.com/dastrobu/AccelerateArray/actions/runs/7241167505/job/19724963804

[dd-bmunge]

I am experiencing the same issue. Did you figure out a solution?

[dastrobu]

Unfortunately no. Was hoping for a response from the maintainers.

[johnbushnell]

Same issue. I'm using the export command in the IDE.

An unknown error occurred.

theme-settings.json

[tplooker]

I'm also experiencing this issue and it is replicate-able on Apple's own documentation for this plugin, if you follow that link the same issue occurs. Would be great if the maintainers could look into this and provide feedback.

[tplooker]

@dastrobu just as an FYI your documentation appears to be rendering at this url.

I'm at a loss as to explaining the URL structuring this tool appears to enforce, I can't find any documentation explaining it and it certainly isn't intuitive. It would appear the HTML hosted at the root path e.g https://dastrobu.github.io/AccelerateArray/ is never actually useful for anything, for example Apples own documentation for this tool at the equivalent path just generates the same error see https://apple.github.io/swift-docc-plugin. So I don't know why the contents of /documentation/<targetName> is not just served from /.