CODEWITHSUNDEEP
swiftwindowsdocumentationntfsdocc
Richard Topchii
Richard Topchii

Reputation: 8165

Make generated DocC documentation compatible with the Windows NTFS file system

Laser-focused StackOverflow Compliant Question: How to make Apple's DocC static files compatible with Windows' NTFS file system, so that it would be possible to review, move files around on Windows as a step in the documentation processing.

Currently we're using DocC to generate the documentation. Our pipeline works as follows:

  1. Create doccarchive

     xcodebuild docbuild \
 -scheme ${SCHEME_NAME} \
 -destination 'generic/platform=iOS' \

  2. Transforming the generated doccarchive for static hosting:

     $(xcrun --find docc) process-archive \
 transform-for-static-hosting "${DOCS_OUTPUT_PATH}/${MODULE_NAME}.doccarchive" \
 --output-path ${DOCS_OUTPUT_PATH}/docs

As, for example, mentioned here: Publishing DocC Documentation as a Static Website on GitHub Pages

  1. Some processing steps (adding or editing links, proofreading, etc).

Then we publish the result on a web server.

The problem occurs at the step 3:

We're able to edit the resulting html pages on macOS/linux machines, however, we cannot edit the contents on the Windows computers due to the fact that the windows changes file & folder structure when unarchiving the documentation archive. Example:

On macOS, the following folder name is changed:

!=(_:_:) -> !=(_/_/)

While on Windows, I'm getting the following errors while unarchiving the resulting archive:

enter image description here

enter image description here

Questions

  1. Is there any way to tweak the DocC output so that it would produce cross-platform-safe html pages?
  2. I see there is a pull request open for about a year, is it so that the work has essentially stalled and DocC is a macOS / Linux-only tool? SwiftDocC: use "portable" paths for file names #668
  3. Any way to tweak the DocC to avoid emitting characters such as ":" in the folder / file names, e.g. as is already done with the DocC documentation? Documentation / DocC / API Documentation / Options / AutomaticTitleHeading Or is the DocC documentation built without using DocC itself?

Upvotes: 1

Views: 62

Answers (0)

Related Questions