Support for DocC experimental features

Development Swift-DocC
,
1

Hi. Recently in the documentation workgroup, we considered the possibility of Swift Package Index supporting Quick Navigation by hosting a few documentations with the QN feature flag set to true, allowing folks to try it out and see if they like it.

To do this, we have to decide which packages will add QN and discuss with SPI maintainers if this is feasible from the implementation perspective.

QN can be enabled by adding a theme-settings.json file on the root of the documentation catalog.

{
  "features": { 
    "docs": { 
      "quickNavigation": { 
        "enable": true 
      } 
    } 
  }
}

(Documentation)

Then the documentation needs to be generated either directly invoking xcrun docc or through the swift-docc-plugin, both using a development snapshot of Swift from at least the 2nd of November (this is the first one that contains the QN changes).

I'm not familiarized with the build process that SPI uses for hosting documentation, so I cannot provide exact details on what needs to be done, but I'm happy to collaborate with the maintainers to sort out the implementation, so please @finestructure @daveverwer let me know your thoughts on this matter and if this is something we could have on the near future.

This would help to accomplish the following:

  1. Getting feedback from folks regarding Quick Navigation and consider enabling it by default
  2. Improve the discoverability of new features
  3. Creating a starting point for implementing an infrastructure into SPI that allows early support for docc and docc-render features

Also, I hope this serves as a guide for those that wish to add Quick Navigation to their documentation.

I look forward to hearing your thoughts!

2 Likes
2

Hi Sofía, I just wanted to follow up our discussion from Monday to add that we're tracking our support for this here: Preview DocC feature on staging · Issue #2129 · SwiftPackageIndex/SwiftPackageIndex-Server · GitHub

I'll be posting updates to that issue as we go along and we can discuss details there or on our Discord!

3 Likes
3

SofĂ­a, could you help me out figuring out which toolchain to install or how to quickly verify I've got the right one?

On swift.org I see

  • Trunk Development (main), nightly-focal, November 3, 2022
  • Swift 5.7 Development, nightly-5.7-focal, October 3, 2022

That would suggest I'd have to use the "Trunk" version. However, that's essentially tracking 5.8, isn't it?

The reason this might be relevant is that we're building the docs after building the package. That way we don't have to rebuild the whole package. I suspect if we used a 5.8 toolchain we'd have to rebuild everything.

Now I'm not sure we could mix and match 5.7.1 release and 5.7-nightly but our chances are probably better that we can. So I'd like to find a nightly 5.7 toolchain with your changes, if possible.

I see that the docker tags are updated daily, so I'm guessing there are macOS 5.7 nightly toolchains available somewhere as well.

Would you or someone else happen to know if that's the case and what the URL is? I tried substituting in a few dates in November for https://download.swift.org/swift-5.7-branch/xcode/swift-5.7-DEVELOPMENT-SNAPSHOT-2022-10-03-a/swift-5.7-DEVELOPMENT-SNAPSHOT-2022-10-03-a-osx.pkg without any luck.

Thanks!

Sven

4

Yes, the trunk version tracks 5.8.

AFAIK there's no release of Swift 5.7 that includes theme customization for DocC, the only version with these changes is the one from the trunk development toolchain.

We could generate the documentation using 5.7-nightly, docc-plugin, and docc-render from the source. To do this, you would have to clone the repo and point to the custom render.

export DOCC_HTML_DIR="/path/to/swift-docc-render-artifact/dist"

(GitHub - apple/swift-docc: Documentation compiler that produces rich API reference documentation and interactive tutorials for your Swift framework or package.)

I remember @ethankusters mentioned something similar at our Monday meeting, so he might be able to confirm if this is the best approach.

5

Thanks for the pointers, SofĂ­a!

If there's no readily usable 5.7 with those changes, let me explore the impact of changing our builder to use main/5.8 for our 5.7 builds in general on staging, or just eating the processing cost of "double building" when we generate the docs.

Given that we're not going to open this up for all packages we can probably live with that, at least at first.

6

We're almost done implementing this but have hit a weird last minute error. When generating the docs on our build machine, we're getting a "Bad CPU type in executable" error with the Nov 3 nightly toolchain. This works fine with the regular 5.7 toolchain.

Our build machine is an M1 Mac mini which doesn't have Rosetta installed. That might explain why in my testing this same command works fine on my M1 MBP which has Rosetta.

Is there anything new in the 5.8 doc generation workflow that might be calling out to an x86 only binary? We can install Rosetta on the build machines if need be but if we can avoid it that'd be even better.

Here's the whole command sequence that replicates our process and works on my machine but fails on our builder with the above mentioned error:

git clone --depth=1 --branch 0.3.5 "https://github.com/SwiftPackageIndex/SemanticVersion.git"

cd SemanticVersion

mkdir -p .docs/swiftpackageindex/semanticversion

cat <<EOF >> Package.swift

package.dependencies.append(
    .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0")
)
EOF

xcrun --toolchain "org.swift.57202211031a" env DOCC_JSON_PRETTYPRINT="YES" swift package --allow-writing-to-directory ".docs/swiftpackageindex/semanticversion/0.3.5" generate-documentation --disable-indexing --transform-for-static-hosting --output-path ".docs/swiftpackageindex/semanticversion/0.3.5" --hosting-base-path "swiftpackageindex/semanticversion/0.3.5" --target "SemanticVersion"
1 Like
7

Oh, it's actually the docc binary in that toolchain itself that's x86 only:

❯ file /Library/Developer/Toolchains/swift-DEVELOPMENT-SNAPSHOT-2022-11-03-a.xctoolchain/usr/bin/docc
/Library/Developer/Toolchains/swift-DEVELOPMENT-SNAPSHOT-2022-11-03-a.xctoolchain/usr/bin/docc: Mach-O 64-bit executable x86_64

vs

❯ file /Applications/Xcode-14.1.0.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/docc
/Applications/Xcode-14.1.0.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/docc: Mach-O universal binary with 2 architectures: [x86_64:Mach-O 64-bit executable x86_64] [arm64]
/Applications/Xcode-14.1.0.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/docc (for architecture x86_64):	Mach-O 64-bit executable x86_64
/Applications/Xcode-14.1.0.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/docc (for architecture arm64):	Mach-O 64-bit executable arm64

I've also checked the latest toolchain from Nov 19 and that's also x86 only, so this looks like a config issue building the binary. It looks like it's the only binary in the toolchains that's not universal.

Where's the best place to report this? Or is there someone I should tag into this discussion?

Thanks in advance!

8

That's unexpected. Can you please file a GitHub issue in the swift-docc repo? cc @ethankusters @ronnqvist

1 Like
9

Done!

3 Likes
10

This is now live in our dev environment. We are currently allow-listing the following three packages for doc previews:

Please let us know via DM or the implementation issue if there are other packages you'd like to see previewed!

2 Likes
11

Thanks a lot for all your work on this @finestructure! QN seems to be working great on those docs :smile:

1 Like
12

And it’s such a great feature! Sorry, I was so focused on getting the preview sorted that I completely neglected to comment how nice it is to have that search available :slightly_smiling_face:

Well done, can’t wait to see it across all docs!

1 Like