Any way to support static site (GitHub pages) hosting multiple framework documentations ?

[dreampiggy]

Feature Request:

Description:

Hi. Swift DocC team. Sorry to bother, but I seems hard to find the correct way to do this, I wonder if this is a feature request or just Swift 5.7 beta bug ?

After watching the WWDC 22 video and following the steps, I can deploy the documentation on GitHub site using the new --transform-for-static-hosting args.

However, I found it hard to deploy multiple framework documentations into single one static site.

For example, my side project SDWebImage contains more than 10 individual framework. Including another framework SDWebImageSwiftUI for example.

My trick way

Here is what I've done currently. I found the index.json files can not been queried for different framework, without modifing the original JS documentation-topic~topic~tutorials-overview.bd94ab17.js to replace the hard-coded index.json with the index/${framework_name}/index.json

(Another issue, what's the original un-minified source code for those JS/CSS files ?) Found swift-docc-render

mkdir site
// Just create an empty target to grab all the needed Images, JS, CSS, HTMLs
cp -R Template.doccarchive/* site/
rm -rf site/data/template.json site/data/template documentation/data/template.json 

// copy SDWebImage documentation
cp -R SDWebImage.doccarchive/documentation/sdwebimage site/documentation/sdwebimage
cp -R SDWebImage.doccarchive/data/sdwebimage site/data/sdwebimage
cp -R SDWebImage.doccarchive/data/sdwebimage.json site/data/sdwebimage.json
cp -R SDWebImage.doccarchive/index/index.json site/index/sdwebimage/index.json

// copy SDWebImageSwiftUI documentation
cp -R SDWebImageSwiftUI.doccarchive/documentation/sdwebimageswiftui site/documentation/sdwebimageswiftui
cp -R SDWebImageSwiftUI.doccarchive/data/sdwebimageswiftui site/data/sdwebimageswiftui
cp -R SDWebImageSwiftUI.doccarchive/data/sdwebimageswiftui.json site/data/sdwebimageswiftui.json
cp -R SDWebImageSwiftUI.doccarchive/index/index.json site/index/sdwebimageswiftui/index.json

Well, this is the final result:

https://sdwebimage.github.io/documentation/sdwebimage/
https://sdwebimage.github.io/documentation/sdwebimageswiftui

Motivation:

Replace this paragraph with a description of the use-case this proposal is trying to serve.

Importance:

Not so important beacuse I can use the tricks above to solve the problem. But need an official way is better.

Alternatives Considered

Seems this is related to #204

[dreampiggy]

Maybe I can ask @Kyle-Ye for help 😂, however he may in holiday...

[franklinsch]

Hi @dreampiggy, thanks for filing this! We're tracking support for this in #255.

[Kyle-Ye]

Maybe I can ask @Kyle-Ye for help 😂, however he may in holiday...

@dreampiggy
If it was multiple targets in a single Package. You can refer to the following PRs

https://github.com/apple/swift-docc/pull/109/files#diff-39548d3d9e7f489ee01bd309d7cc42011188f96006165781d64e3d6ffa269b55

Result:

• https://apple.github.io/swift-docc/documentation/swiftdocc/
• https://apple.github.io/swift-docc/documentation/swiftdoccutilities/

https://github.com/apple/swift-async-algorithms/pull/137/files/20d1a574cb7899ec027d06a3efc84c8c681d8319#diff-39548d3d9e7f489ee01bd309d7cc42011188f96006165781d64e3d6ffa269b55

Result:

• base://swift-async-algorithms/documentation/asyncalgorithms
• base://swift-async-algorithms/documentation/asyncsequencevalidation

TL;DR:
Use swift-docc-plugin and copy the another target's result into the original documentation foloder.

swift package <target1> // Build doc for target 1
swift package <target2> // Build doc for target 2
cp -R <target 2 doc result> <target 1 doc result> // Merge the 2 targets' documentation

Looks like this is still a feature waiting for implementation and tracked via #255.

[dreampiggy]

It's not Multiple Target inside single Swift Package (Monorepo like)

It's Multiple Swift Package which contains each of Target (Multirepo like)

Just as if I'm in Apple, and want to merge different Team's CoreFoundation.doccarchive, UIKit.doccarchive, ARKit.doccarchive into single https://developer.apple.com/documentation/ site

[dreampiggy]

And also...Though not really relavant.

The current release swift-docc-plugin support only Swift target, but not Objective-C target. Which will show like this 🙃 So I have to use Xcode 14 or self built docc binary to generate the folder.

[Kyle-Ye]

And also...Though not really relavant.

The current release swift-docc-plugin support only Swift target, but not Objective-C target. Which will show like this 🙃 So I have to use Xcode 14 or self built docc binary to generate the folder.

For the issue of swift-docc-plugin not supporting ObjectiveC, maybe you can open a issue or feature request here https://github.com/apple/swift-docc-plugin/issues/new/choose

[TosinAF]

@dreampiggy Did you do this and if so how?
Here is what I've done currently. I found the index.json files can not been queried for different framework, without modifing the original JS documentation-topictopictutorials-overview.bd94ab17.js to replace the hard-coded index.json with the index/${framework_name}/index.json

[Kyle-Ye]

And also...Though not really relavant.

The current release swift-docc-plugin support only Swift target, but not Objective-C target. Which will show like this 🙃 So I have to use Xcode 14 or self built docc binary to generate the folder.

I've finished a prototype PR for ObjC support @dreampiggy
You can check and try it here swiftlang/swift-docc-plugin#56

[dreampiggy]

Yes. I use it indeed till today , in https://sdwebimage.github.io/

Open that page to show the result which combine 5 individual github repo (Multirepo) and their DocC html into one page.

The script I used just in this PR, by replacing the code in Xcode's vendored Minified JS. Which is Xcode 14.1. Just be stupid and use text editor to replace:

"index.json" to "index/"+window.location.pathname.split('/')[2]+"/index.json"

See: https://github.com/SDWebImage/sdwebimage.github.io/blob/master/patches/documentation-topic~topic~tutorials-overview.bd94ab17.js.diff

[dreampiggy]

Then you need to copy all things, html pages, index.json, and with the sub folder structure.

See how I've done for SDWebImage (ugly hack): https://github.com/SDWebImage/sdwebimage.github.io#build-and-found-the-doccarchive

But anyway, I will migrate to Monorepo in the future and put all code into one Swift Package with 12 different targets. Maybe at that time I will use different solution.