docczz / docc2html Goto Github PK

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: Apodini/Template-Repository#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 Apodini/Template-Repository#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?

We've got multiple modules that all really should reference each other. Any chance this could be adapted to combine multiple doccarchives?

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?

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

The current CSS is hardcoded for desktop, it needs the proper media queries to layout better on mobile devices.

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!

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 5588eb6 here.

Please release a new version. Thank you!

Would allow easy customization and would it make easier to test new templates w/o having to recompile the tool.

It might make sense to generate index.html files for the folders after exporting the site. Could be just a link to the primary html file, or a TOC.

Hi all,

Getting the following error when running

swift run docc2html --force ~/Documents/NaurtSDK.doccarchive/ ~/Documents/

I'm using 7a64add (current latest on develop).

I exported the doccarchive from the latest version of XCode, 15.0

ERROR: dataCorrupted(Swift.DecodingError.Context(codingPath: [CodingKeys(stringValue: "metadata", intValue: nil), MetaDataCodingKeys(stringValue: "roleHeading", intValue: nil)], debugDescription: "Cannot initialize RoleHeading from invalid String value Function", underlyingError: nil))
2023-10-13T11:31:06+0100 error docc2html : [DocCStaticExporter] Could not process document at: /Users/nathanielcurnick/Documents/NaurtSDK.doccarchive/data/documentation/naurtsdk/distancebetween(_:_:).json dataCorrupted(Swift.DecodingError.Context(codingPath: [CodingKeys(stringValue: "metadata", intValue: nil), MetaDataCodingKeys(stringValue: "roleHeading", intValue: nil)], debugDescription: "Cannot initialize RoleHeading from invalid String value Function", underlyingError: nil))

It's having trouble with this distanceBetween function. Here's the signature

public func distanceBetween(_ a: Location2D, _ b: Location2D) -> Double

And the definition for Location2D (not sure if this is relevant)

@objc public class Location2D: NSObject

Looks like it might be related to #7 and #20

Following on from #21 , DocCArchive was updated to 0.3.4. I made a pull request #22. It did fix the RoleHeading error, but that's lead onto several new errors around data corruption

ERROR: dataCorrupted(Swift.DecodingError.Context(codingPath: [CodingKeys(stringValue: "metadata", intValue: nil), MetaDataCodingKeys(stringValue: "symbolKind", intValue: nil)], debugDescription: "Cannot initialize SymbolKind from invalid String value func", underlyingError: nil))

2023-10-16T08:58:44+0100 error docc2html : [DocCStaticExporter] Could not process document at: /Users/nathanielcurnick/Documents/NaurtSDK.doccarchive/data/documentation/naurtsdk/distancebetween(_:_:).json dataCorrupted(Swift.DecodingError.Context(codingPath: [CodingKeys(stringValue: "metadata", intValue: nil), MetaDataCodingKeys(stringValue: "symbolKind", intValue: nil)], debugDescription: "Cannot initialize SymbolKind from invalid String value func", underlyingError: nil))

ERROR: dataCorrupted(Swift.DecodingError.Context(codingPath: [CodingKeys(stringValue: "identifier", intValue: nil), CodingKeys(stringValue: "interfaceLanguage", intValue: nil)], debugDescription: "Cannot initialize InterfaceLanguage from invalid String value occ", underlyingError: nil))

2023-10-16T08:58:44+0100 error docc2html : [DocCStaticExporter] Could not process document at: /Users/nathanielcurnick/Documents/NaurtSDK.doccarchive/data/documentation/naurtsdk/naurtsdkversionnumber.json dataCorrupted(Swift.DecodingError.Context(codingPath: [CodingKeys(stringValue: "identifier", intValue: nil), CodingKeys(stringValue: "interfaceLanguage", intValue: nil)], debugDescription: "Cannot initialize InterfaceLanguage from invalid String value occ", underlyingError: nil))

ERROR: dataCorrupted(Swift.DecodingError.Context(codingPath: [CodingKeys(stringValue: "identifier", intValue: nil), CodingKeys(stringValue: "interfaceLanguage", intValue: nil)], debugDescription: "Cannot initialize InterfaceLanguage from invalid String value occ", underlyingError: nil))

2023-10-16T08:58:44+0100 error docc2html : [DocCStaticExporter] Could not process document at: /Users/nathanielcurnick/Documents/NaurtSDK.doccarchive/data/documentation/naurtsdk/naurtsdkversionstring.json dataCorrupted(Swift.DecodingError.Context(codingPath: [CodingKeys(stringValue: "identifier", intValue: nil), CodingKeys(stringValue: "interfaceLanguage", intValue: nil)], debugDescription: "Cannot initialize InterfaceLanguage from invalid String value occ", underlyingError: nil))

ERROR: dataCorrupted(Swift.DecodingError.Context(codingPath: [CodingKeys(stringValue: "identifier", intValue: nil), CodingKeys(stringValue: "interfaceLanguage", intValue: nil)], debugDescription: "Cannot initialize InterfaceLanguage from invalid String value occ", underlyingError: nil))

2023-10-16T08:58:44+0100 error docc2html : [DocCStaticExporter] Could not process document at: /Users/nathanielcurnick/Documents/NaurtSDK.doccarchive/data/documentation/naurtsdk/poierrordomain.json dataCorrupted(Swift.DecodingError.Context(codingPath: [CodingKeys(stringValue: "identifier", intValue: nil), CodingKeys(stringValue: "interfaceLanguage", intValue: nil)], debugDescription: "Cannot initialize InterfaceLanguage from invalid String value occ", underlyingError: nil))

Unfortunately, these error messages mean a lot less to me now, let me know if you need any code snippets

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"}}}

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.

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.

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 :)

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

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": {}
}