docc2html - A static site generator for DocC documentation archives

Hi! Was getting an error when trying to generate the static HTML from a .doccarchive file.

Could not process document at: /Users/rafael/Desktop/MyProject.doccarchive/data/documentation/myproject/http.json keyNotFound(CodingKeys(stringValue: "documentVersion", intValue: nil), Swift.DecodingError.Context(codingPath: [], debugDescription: "No value associated with key CodingKeys(stringValue: \"documentVersion\", intValue: nil) (\"documentVersion\").", underlyingError: nil)) It seems to happen for several different files throughout the project.

Cheers!

First of all, thanks for the excellent work with this package @helje5 ! Thanks for filling in the hole of

Deployment to GitHub Pages

As noted in your README, deploying the generated HTML pages to GitHub Pages within a GitHub Action would be a helpful addition. I have played around with this and created the following action to do so and wanted to share this with you: https://github.com/Apodini/Template-Repository/blob/feature/docCGitHubPages/.github/workflows/docs.yml It uses xcodebuild to generate the documentation and your tool to generate a static HTML page that is then published to the gh-pages branch.

Feel free to reuse and share this GitHub Action if you find it useful.

Open Issues

The GitHub Action is part of the following pull request to add this to our template repo: https://github.com/Apodini/Template-Repository/pull/8 . While working on the PR, I found the following issues that I wanted to share with you:

1. GH Pages requires an index.html file at the root of the gh-pages branch. I have circumvented this by simply creating a basic HTML page in the GitHub Action that redirects to the index.html page found in the subfolders. It would probably be a nice addition to generate this directly using docc2html?
2. As noted in the comments of https://github.com/Apodini/Template-Repository/pull/8 there is an issue with the links between the different HTML pages. As the name of the type as well as the name of the target contains upper case characters, the links result in 404 errors. I think the solution would be to either make sure that all links between pages are only using lowercase characters or changing the folder structure to allow upper case characters as found in the Swift types, functions, etc. What do you think?

Using the newest 0.2.9 version:

1. Unsupported Inline Content Type "link"

2021-08-11T14:44:00+0200 error docc2html : Could not process document at: /Users/jakubtowarek/Projects/[reducted]/docc/Build/Products/Debug-iphoneos/[reducted].doccarchive/data/documentation/changelog.json unsupportedInlineContentType("link")

Only JSON objects having "type": "link" are in the "references" object:

"references": {
    "https://keepachangelog.com/en/1.0.0/": {
      "title": "Keep a Changelog",
      "titleInlineContent": [
        {
          "type": "text",
          "text": "Keep a Changelog"
        }
      ],
      "type": "link",
      "identifier": "https://keepachangelog.com/en/1.0.0/",
      "url": "https://keepachangelog.com/en/1.0.0/"
    },
    "https://github.com/3Qax": {
      "title": "@3Qax",
      "titleInlineContent": [
        {
          "type": "text",
          "text": "@3Qax"
        }
      ],
      "type": "link",
      "identifier": "https://github.com/3Qax",
      "url": "https://github.com/3Qax"
    },
    "https://semver.org/spec/v2.0.0.html": {
      "title": "Semantic Versioning",
      "titleInlineContent": [
        {
          "type": "text",
          "text": "Semantic Versioning"
        }
      ],
      "type": "link",
      "identifier": "https://semver.org/spec/v2.0.0.html",
      "url": "https://semver.org/spec/v2.0.0.html"
    },
    "doc://com.[reducted].[reducted]/documentation/[reducted]": {
      "role": "collection",
      "title": "[reducted]",
      "abstract": [
        {
          "type": "text",
          "text": "A iOS library of components, atoms and organisms for [reducted] consumer-facing products."
        }
      ],
      "identifier": "doc://com.[reducted].[reducted]/documentation/[reducted]",
      "kind": "symbol",
      "type": "topic",
      "url": "/documentation/[reducted]"
    }
  }

from markdown like:

# Changelog
All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
...

2. Support for warning aside

ERROR: dataCorrupted(Swift.DecodingError.Context(codingPath: [CodingKeys(stringValue: "primaryContentSections", intValue: nil), _JSONKey(stringValue: "Index 1", intValue: 1), CodingKeys(stringValue: "content", intValue: nil), _JSONKey(stringValue: "Index 1", intValue: 1), CodingKeys(stringValue: "style", intValue: nil)], debugDescription: "Cannot initialize Style from invalid String value warning", underlyingError: nil))
2021-08-11T14:43:59+0200 error docc2html : Could not process document at: /Users/jakubtowarek/Projects/[reducted]/docc/Build/Products/Debug-iphoneos/[reducted].doccarchive/data/documentation/[reducted]/dscounter/count.json dataCorrupted(Swift.DecodingError.Context(codingPath: [CodingKeys(stringValue: "primaryContentSections", intValue: nil), _JSONKey(stringValue: "Index 1", intValue: 1), CodingKeys(stringValue: "content", intValue: nil), _JSONKey(stringValue: "Index 1", intValue: 1), CodingKeys(stringValue: "style", intValue: nil)], debugDescription: "Cannot initialize Style from invalid String value warning", underlyingError: nil))

for documentation generated for:

    /// Count
    /// - Warning: Values above `99` will be shown as `99+`.
    @IBInspectable public var count: UInt = 0

or

    /// Count
    /// > Warning: Values above `99` will be shown as `99+`.
    @IBInspectable public var count: UInt = 0

I took a peak at sources and I see DocCArchive.DocCSchema_0_1.Content.Style has only note style, while DocC seem to be defining:

• Note
• Important
• Warning
• Tip
• Experiment

Hello, I absolutely love your project and I think it should be default for DocC to generate static pages.

Here is one out of 3 errors I encountered while using this tool:

ERROR: unsupportedFragmentKind("attribute")
2021-08-11T11:52:44+0200 error docc2html : Could not process document at: /Users/jakubtowarek/Projects/[reducted]/docc/Build/Products/Debug-iphoneos/[reducted].doccarchive/data/documentation/[reducted]/dscounter/count.json unsupportedFragmentKind("attribute")

in the following JSON file attribute is only in one place (at the very beginning) :

{
  "primaryContentSections": [
    {
      "kind": "declarations",
      "declarations": [
        {
          "tokens": [
            {
              "kind": "attribute",
              "text": "@IBInspectable"
            },

so I suppose there's an issue with parsing @IBInspecatble and @IBDesignable attributes. I am happy to provide any additional information that might be helpful to fix this :)

This used to cause excessive horizontal scrolling in below component, as .large-3 (50%) and .large-9 (75%) together had more than 125% width.

https://github.com/DoccZz/docc2html/blob/5588eb6377339e8a982a74d5dfb34f2ed315f5a0/Templates/Sections.mustache#L7-L13

Hi!

The dependency to DocCArchive in Package.swift

.package(url  : "https://github.com/DoccZz/DocCArchive.git",
             from : "0.3.2"),

contains a .link case in https://github.com/DoccZz/DocCArchive/blob/develop/Sources/DocCArchive/Schema_0_1/References/Reference.swift#L24

which is only considered in the latest commit https://github.com/DoccZz/docc2html/commit/5588eb6377339e8a982a74d5dfb34f2ed315f5a0 here.

Please release a new version. Thank you!

and the 3rd one, but the most painful since it's preventing my landing page's index.html generation:

ERROR: unsupportedContentType("unorderedList")
2021-08-11T11:52:45+0200 error docc2html : Could not process document at: /Users/jakubtowarek/Projects/[reducted]/docc/Build/Products/Debug-iphoneos/[reducted].doccarchive/data/documentation/[reducted]/changelog.json unsupportedContentType("unorderedList")

{
  "primaryContentSections": [
    {
      "kind": "content",
      "content": [
        {
          "anchor": "Added",
          "level": 3,
          "type": "heading",
          "text": "Added"
        },
        {
          "type": "unorderedList",
          "items": [
            {
              "content": [
                {
                  "type": "paragraph",
                  "inlineContent": [
                    {
                      "type": "text",
                      "text": "Counter component "
                    },
                    {
                      "type": "reference",
                      "isActive": true,
                      "identifier": "https://github.com/3Qax"
                    }
                  ]
                }
              ]
            },
            {
              "content": [
                {
                  "type": "paragraph",
                  "inlineContent": [
                    {
                      "type": "text",
                      "text": "Changelog.md"
                    },
                    {
                      "overridingTitleInlineContent": [
                        {
                          "type": "text",
                          "text": "@3Qax"
                        }
                      ],
                      "isActive": true,
                      "type": "reference",
                      "identifier": "https://github.com/3Qax",
                      "overridingTitle": "@3Qax"
                    }
                  ]
                }
              ]
            }
          ]
        }
  ],
  "schemaVersion": {
    "major": 0,
    "minor": 1,
    "patch": 0
  },
  "sections": [],
  "variants": [],
  "identifier": {},
  "abstract": [],
  "kind": "article",
  "metadata": {},
  "hierarchy": {},
  "documentVersion": 0,
  "references": {}
}

The tool is quick and dirty hack, full of shortcuts :-)

It would be nice to push the generation facility into a proper library that could also be embedded into other apps. Not a big job, just needs to be done.

Hello,

i'm having trouble to generate an html document from the doccarchive. I looked through the list of issues (open & closed) and found someone had an simular issue here (in the second half) but i didnt get what to do. I'm running the latest xcode version (Version 13.4).

Thanks in advance

Here are the error from the console:

ERROR: dataCorrupted(Swift.DecodingError.Context(codingPath: [CodingKeys(stringValue: "metadata", intValue: nil), MetaDataCodingKeys(stringValue: "roleHeading", intValue: nil)], debugDescription: "Cannot initialize RoleHeading from invalid String value Application", underlyingError: nil)) 2022-05-23T23:57:39+0200 error docc2html : Could not process document at: /Users/Username/Desktop/RobotNavigation.doccarchive/data/documentation/robotnavigation.json dataCorrupted(Swift.DecodingError.Context(codingPath: [CodingKeys(stringValue: "metadata", intValue: nil), MetaDataCodingKeys(stringValue: "roleHeading", intValue: nil)], debugDescription: "Cannot initialize RoleHeading from invalid String value Application", underlyingError: nil))

and regarding to that error here is the "robotnavigation.json"

{"variants":[{"paths":["\/documentation\/robotnavigation"],"traits":[{"interfaceLanguage":"swift"}]}],"schemaVersion":{"major":0,"minor":2,"patch":0},"sections":[],"identifier":{"url":"doc:\/\/com.lennart.RobotNavigation\/documentation\/RobotNavigation","interfaceLanguage":"swift"},"abstract":[{"type":"text","text":""}],"kind":"symbol","metadata":{"roleHeading":"Application","externalID":"RobotNavigation","title":"RobotNavigation","symbolKind":"module","role":"collection","modules":[{"name":"RobotNavigation"}]},"hierarchy":{"paths":[[]]},"topicSections":[{"title":"Classes","identifiers":["doc:\/\/com.lennart.RobotNavigation\/documentation\/RobotNavigation\/AppDelegate","doc:\/\/com.lennart.RobotNavigation\/documentation\/RobotNavigation\/BlePeripheral","doc:\/\/com.lennart.RobotNavigation\/documentation\/RobotNavigation\/NavigationViewController","doc:\/\/com.lennart.RobotNavigation\/documentation\/RobotNavigation\/SceneDelegate","doc:\/\/com.lennart.RobotNavigation\/documentation\/RobotNavigation\/ViewController"]},{"title":"Structures","identifiers":["doc:\/\/com.lennart.RobotNavigation\/documentation\/RobotNavigation\/CBUUIDs"]}],"references":{"doc://com.lennart.RobotNavigation/documentation/RobotNavigation/ViewController":{"role":"symbol","title":"ViewController","fragments":[{"kind":"keyword","text":"class"},{"kind":"text","text":" "},{"kind":"identifier","text":"ViewController"}],"abstract":[],"identifier":"doc:\/\/com.lennart.RobotNavigation\/documentation\/RobotNavigation\/ViewController","kind":"symbol","type":"topic","navigatorTitle":[{"kind":"identifier","text":"ViewController"}],"url":"\/documentation\/robotnavigation\/viewcontroller"},"doc://com.lennart.RobotNavigation/documentation/RobotNavigation/SceneDelegate":{"role":"symbol","title":"SceneDelegate","fragments":[{"kind":"keyword","text":"class"},{"kind":"text","text":" "},{"kind":"identifier","text":"SceneDelegate"}],"abstract":[],"identifier":"doc:\/\/com.lennart.RobotNavigation\/documentation\/RobotNavigation\/SceneDelegate","kind":"symbol","type":"topic","navigatorTitle":[{"kind":"identifier","text":"SceneDelegate"}],"url":"\/documentation\/robotnavigation\/scenedelegate"},"doc://com.lennart.RobotNavigation/documentation/RobotNavigation/NavigationViewController":{"role":"symbol","title":"NavigationViewController","fragments":[{"kind":"keyword","text":"class"},{"kind":"text","text":" "},{"kind":"identifier","text":"NavigationViewController"}],"abstract":[{"type":"text","text":"Description"}],"identifier":"doc:\/\/com.lennart.RobotNavigation\/documentation\/RobotNavigation\/NavigationViewController","kind":"symbol","type":"topic","navigatorTitle":[{"kind":"identifier","text":"NavigationViewController"}],"url":"\/documentation\/robotnavigation\/navigationviewcontroller"},"doc://com.lennart.RobotNavigation/documentation/RobotNavigation/AppDelegate":{"role":"symbol","title":"AppDelegate","fragments":[{"kind":"keyword","text":"class"},{"kind":"text","text":" "},{"kind":"identifier","text":"AppDelegate"}],"abstract":[],"identifier":"doc:\/\/com.lennart.RobotNavigation\/documentation\/RobotNavigation\/AppDelegate","kind":"symbol","type":"topic","navigatorTitle":[{"kind":"identifier","text":"AppDelegate"}],"url":"\/documentation\/robotnavigation\/appdelegate"},"doc://com.lennart.RobotNavigation/documentation/RobotNavigation/CBUUIDs":{"role":"symbol","title":"CBUUIDs","fragments":[{"kind":"keyword","text":"struct"},{"kind":"text","text":" "},{"kind":"identifier","text":"CBUUIDs"}],"abstract":[],"identifier":"doc:\/\/com.lennart.RobotNavigation\/documentation\/RobotNavigation\/CBUUIDs","kind":"symbol","type":"topic","navigatorTitle":[{"kind":"identifier","text":"CBUUIDs"}],"url":"\/documentation\/robotnavigation\/cbuuids"},"doc://com.lennart.RobotNavigation/documentation/RobotNavigation":{"role":"collection","title":"RobotNavigation","abstract":[],"identifier":"doc:\/\/com.lennart.RobotNavigation\/documentation\/RobotNavigation","kind":"symbol","type":"topic","url":"\/documentation\/robotnavigation"},"doc://com.lennart.RobotNavigation/documentation/RobotNavigation/BlePeripheral":{"role":"symbol","title":"BlePeripheral","fragments":[{"kind":"keyword","text":"class"},{"kind":"text","text":" "},{"kind":"identifier","text":"BlePeripheral"}],"abstract":[],"identifier":"doc:\/\/com.lennart.RobotNavigation\/documentation\/RobotNavigation\/BlePeripheral","kind":"symbol","type":"topic","navigatorTitle":[{"kind":"identifier","text":"BlePeripheral"}],"url":"\/documentation\/robotnavigation\/bleperipheral"}}}

Current Issue

If the name of the type or the target's name contains upper case characters results in links generated by docc2html results in 404 errors. docc2html generates an html page for a taget named TargetName, type name TypeName, and function name test at the following path: /documentation/targetname/typename/test(_:).html even though the links embedded in other pages look like this /documentation/TargetName/TypeName/test(_:).html.

You can reproduce the issue in the following GitHub Pages based deployment: https://apodini.github.io/Template-Repository/documentation/apodinitemplate/apodinitemplate/index.html The link to the greet function in the HTML page is https://apodini.github.io/Template-Repository/documentation/ApodiniTemplate/ApodiniTemplate/greet(_:).html while the HTML page can be found at https://apodini.github.io/Template-Repository/documentation/apodinitemplate/apodinitemplate/greet(_:).html

Related Issues

The issue was first noted in issue #13

ERROR: dataCorrupted(Swift.DecodingError.Context(codingPath: [CodingKeys(stringValue: "metadata", intValue: nil), MetaDataCodingKeys(stringValue: "roleHeading", intValue: nil)], debugDescription: "Cannot initialize RoleHeading from invalid String value Type Method", underlyingError: nil))
2021-08-11T11:52:44+0200 error docc2html : Could not process document at: /Users/jakubtowarek/Projects/[reducted]/docc/Build/Products/Debug-iphoneos/[reducted].doccarchive/data/documentation/[reducted]/[reducted]/getvalue(key:).json dataCorrupted(Swift.DecodingError.Context(codingPath: [CodingKeys(stringValue: "metadata", intValue: nil), MetaDataCodingKeys(stringValue: "roleHeading", intValue: nil)], debugDescription: "Cannot initialize RoleHeading from invalid String value Type Method", underlyingError: nil))

{
  "primaryContentSections": [],
  "schemaVersion": {
    "major": 0,
    "minor": 1,
    "patch": 0
  },
  "sections": [],
  "variants": [],
  "identifier": {},
  "abstract": [],
  "kind": "symbol",
  "metadata": {
    "fragments": [
      {
        "kind": "keyword",
        "text": "class"
      },
      {
        "kind": "text",
        "text": " "
      },
      {
        "kind": "keyword",
        "text": "func"
      },
      {
        "kind": "text",
        "text": " "
      },
      {
        "kind": "identifier",
        "text": "getValue"
      },
      {
        "kind": "text",
        "text": "("
      },
      {
        "kind": "externalParam",
        "text": "key"
      },
      {
        "kind": "text",
        "text": ": "
      },
      {
        "kind": "typeIdentifier",
        "text": "String",
        "preciseIdentifier": "s:SS"
      },
      {
        "kind": "text",
        "text": "?) -> "
      },
      {
        "kind": "typeIdentifier",
        "text": "UIColor",
        "preciseIdentifier": "c:objc(cs)UIColor"
      },
      {
        "kind": "text",
        "text": "?"
      }
    ],
    "title": "getValue(key:)",
    "roleHeading": "Type Method",
    "role": "symbol",
    "symbolKind": "method",
    "externalID": "[reducted]",
    "modules": [
      {
        "name": "[reducted]"
      }
    ]
  },
  "hierarchy": {},
  "documentVersion": 0,
  "references": {}
}

Current Issue

docc2html currently doesn't produce an index.html file at the root of the exported folder that links to the generated HTML files documenting a target. When publishing the documentation as an HTML page, you need to generate an HTML page that links to the targets or automatically forwards to a target if only one target is present.

You can see the issue in the following GitHub Pages based deployment: https://apodini.github.io/Template-Repository/ returns a 404 error. The DocC documentation is successfully found in the subfolders of the HTML export: https://apodini.github.io/Template-Repository/documentation/apodinitemplate/apodinitemplate/index.html

Suggested Solution

It would be great if docc2html could generate an index.html page listing all targets included in the exported documentation and linking to the related index.html pages in the subfolders. If there is only one exported target, the page should automatically link to the only target present in the documentation archive.

Related Issues

The issue was first noted in issue #13

I think this can also be done using just plain CSS (switching the site on light or dark mode).

A small JS button to let the user switch shouldn't be hard either?

This mostly means adding support to generate task sections and figuring out how to generate the step-by-step things in a mostly static way (I guess some JS would be quite OK too).

Also the CSS magic to position things.