search

Automattic / Gravatar-SDK-iOS

Gravatar SDK is a Swift library that allows you to integrate Gravatar features into your own iOS applications.
https://gravatar.com
Mozilla Public License 2.0
36 stars 1 forks source link

Fix Swift Package Index documentation generation #333

Closed andrewdmontgomery closed 1 month ago

andrewdmontgomery commented 1 month ago

Closes #332

Description

This does two things:

Attempt to fix the Swift Package Index doc generation

Here we can see the iOS/Swift 5.10 build that produces an error when attempting to build the documentation: https://swiftpackageindex.com/builds/F8582B6A-864E-40BE-B0C6-32ACE9076F7A

/Applications/Xcode-15.4.0.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/docc convert --index --fallback-display-name Gravatar --fallback-bundle-identifier Gravatar --fallback-bundle-version 0 --output-dir /Users/admin/builder/spi-builder-workspace/.derivedData/Build/Products/Debug-iphoneos/Gravatar.doccarchive --ide-console-output --diagnostics-file /Users/admin/builder/spi-builder-workspace/.derivedData/Build/Intermediates.noindex/Gravatar.build/Debug-iphoneos/Gravatar.build/Gravatar-diagnostics.json --emit-digest --include-extended-types --source-service github --source-service-base-url https://github.com/Automattic/Gravatar-SDK-iOS/blob/trunk --checkout-path /Users/admin/builder/spi-builder-workspace /Users/admin/builder/spi-builder-workspace/Sources/Gravatar/Gravatar.docc --additional-symbol-graph-dir /Users/admin/builder/spi-builder-workspace/.derivedData/Build/Intermediates.noindex/Gravatar.build/Debug-iphoneos/Gravatar.build/symbol-graph
Error: Unknown option '--include-extended-types'
Usage: docc convert [<options>] [<source-bundle-path>]
  See 'docc convert --help' for more information.
Command CompileDocumentation failed with a nonzero exit code
** BUILD DOCUMENTATION FAILED **
The following build commands failed:
    CompileDocumentation /Users/admin/builder/spi-builder-workspace/Sources/Gravatar/Gravatar.docc (in target 'Gravatar' from project 'Gravatar')
(1 failure)
Error while generating docs: retryLimitExceeded(lastError: Optional(Shell command failed:
    env DEVELOPER_DIR=/Applications/Xcode-15.4.0.app xcrun xcodebuild -IDEClonedSourcePackagesDirPathOverride=$PWD/.dependencies -skipMacroValidation -skipPackagePluginValidation -derivedDataPath $PWD/.derivedData docbuild OTHER_DOCC_FLAGS=--emit-digest --include-extended-types --source-service github --source-service-base-url https://github.com/Automattic/Gravatar-SDK-iOS/blob/trunk --checkout-path $PWD -scheme Gravatar -destination generic/platform=iOS))

At first I got hung up on the Error while generating docs: retryLimitExceeded. But after looking more closely, I suspect that just means that the "retry limit" is set to "none", and so the error causes a build failure.

I think the underlying problem is this:

Error: Unknown option '--include-extended-types'

The docc convert command doesn't support that option. So it is exiting immediately with an error code. This PR simply removes that custom option from the configuration.

Fixes the refresh in the root index.html

That second point doesn't affect the documentation generation at Swift Package Index. But it should allow us to visit the following URL's and have them appropriately refresh to the deeper index.html:

Testing Steps

I'm not aware of a way to test these without merging into trunk.

andrewdmontgomery commented 1 month ago

@etoledom For GitHub Pages, why are we overwriting the index.html with a simpler version that refreshes to the deeper path? Presuming we had a good reason for doing that, II have (hopefully) fixed the path in the refresh, so that it doesn't include the gravatar base. It was refreshing to gravatar/gravatar/documentation/gravatar/index.html instead of gravatar/documentation/gravatar/index.html.

But I was curious.

andrewdmontgomery commented 1 month ago

@etoledom I added some context in the description.

andrewdmontgomery commented 1 month ago

I temporarily modify the rules to allow doc builds from the PR branch, just to be sure that everything is fine, and then I revert them before merging.

Ah nice. I see what you mean. That would allow me to push to github pages from my branch. Nice.

I think we'll still have to merge to trunk to see if the SPI file works.

andrewdmontgomery commented 1 month ago

It's interesting that I remember seeing this in other .spi.yml files from other projects (or maybe I got confused)

You probably did. I just found this: https://swiftlang.github.io/swift-docc-plugin/documentation/swiftdoccplugin/generating-documentation-for-extended-types

It's available via swift package generate-documentation. We're using xcodebuild docbuild, though, due to swift package not supporting UIKit/simulators.

etoledom commented 1 month ago

I think we'll still have to merge to trunk to see if the SPI file works.

Ah yes, this for sure 👍 Seems like it should work this time!

andrewdmontgomery commented 1 month ago

Alright, the GitHub Pages changes work (the auto-redirects). 👍

I've reverted my change, and reset the rule for which branches can build (back to just trunk).

I investigated the default index.html files that are generated. The don't load anything. It looks like the baseURL isn't getting set. So the JS resources that should be loading things cannot be found because they are looking for https://automattic.github.io/ instead of https://automattic.github.io/Gravatar-SDK-iOS:

(note: this is loading from local files)

<head><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover"><link rel="icon" href="/favicon.ico"><link rel="mask-icon" href="/favicon.svg" color="#333333"><title>Documentation</title><script>var baseUrl = "/"</script><script defer="defer" src="/js/chunk-vendors.bdb7cbba.js"></script><script defer="defer" src="/js/index.2871ffbd.js"></script><link href="/css/index.ff036a9e.css" rel="stylesheet"></head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
<link rel="icon" href="/favicon.ico">
<link rel="mask-icon" href="/favicon.svg" color="#333333">
<title>Documentation</title>
<script>var baseUrl = "/"</script>
<script defer="defer" src="/js/chunk-vendors.bdb7cbba.js"></script>
<script defer="defer" src="/js/index.2871ffbd.js"></script>
<link href="/css/index.ff036a9e.css" rel="stylesheet">
<head><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover"><link rel="icon" href="/favicon.ico"><link rel="mask-icon" href="/favicon.svg" color="#333333"><title>Documentation</title><script>var baseUrl = "/"</script><script defer="defer" src="/js/chunk-vendors.bdb7cbba.js"></script><script defer="defer" src="/js/index.2871ffbd.js"></script><link href="/css/index.ff036a9e.css" rel="stylesheet"></head>

For contracts, here's the header from the index.html from with the documents/gravatar/ subdirectory:

<head><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover"><link rel="icon" href="/Gravatar-SDK-iOS/gravatar/favicon.ico"><link rel="mask-icon" href="/Gravatar-SDK-iOS/gravatar/favicon.svg" color="#333333"><title>Gravatar | Documentation</title><script>var baseUrl = "/Gravatar-SDK-iOS/gravatar/"</script><script defer="defer" src="/Gravatar-SDK-iOS/gravatar/js/chunk-vendors.bdb7cbba.js"></script><script defer="defer" src="/Gravatar-SDK-iOS/gravatar/js/index.2871ffbd.js"></script><link href="/Gravatar-SDK-iOS/gravatar/css/index.ff036a9e.css" rel="stylesheet"><link rel="stylesheet" type="text/css" href="/Gravatar-SDK-iOS/gravatar/css/523.e9a069b0.css"><link rel="stylesheet" type="text/css" href="/Gravatar-SDK-iOS/gravatar/css/documentation-topic.b186e79f.css"><meta name="description" content="Gravatar iOS SDK"><meta property="og:locale" content="en-US"><meta property="og:site_name" content="Documentation"><meta property="og:type" content="website"><meta property="og:title" content="Gravatar | Documentation"><meta property="og:description" content="Gravatar iOS SDK"><meta property="og:url" content="https://automattic.github.io/Gravatar-SDK-iOS/gravatar/documentation/gravatar/"><meta property="og:image" content="https://automattic.github.io/Gravatar-SDK-iOS/gravatar/developer-og.jpg"><meta name="twitter:image" content="https://automattic.github.io/Gravatar-SDK-iOS/gravatar/developer-og-twitter.jpg"><meta name="twitter:card" content="summary_large_image"><meta name="twitter:description" content="Gravatar iOS SDK"><meta name="twitter:title" content="Gravatar | Documentation"><meta name="twitter:url" content="https://automattic.github.io/Gravatar-SDK-iOS/gravatar/documentation/gravatar/"></head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
<link rel="icon" href="/Gravatar-SDK-iOS/gravatar/favicon.ico">
<link rel="mask-icon" href="/Gravatar-SDK-iOS/gravatar/favicon.svg" color="#333333">
<title>Gravatar | Documentation</title>
<script>var baseUrl = "/Gravatar-SDK-iOS/gravatar/"</script>
<script defer="defer" src="/Gravatar-SDK-iOS/gravatar/js/chunk-vendors.bdb7cbba.js"></script>
<script defer="defer" src="/Gravatar-SDK-iOS/gravatar/js/index.2871ffbd.js"></script>
<link href="/Gravatar-SDK-iOS/gravatar/css/index.ff036a9e.css" rel="stylesheet">
<link rel="stylesheet" type="text/css" href="/Gravatar-SDK-iOS/gravatar/css/523.e9a069b0.css">
<link rel="stylesheet" type="text/css" href="/Gravatar-SDK-iOS/gravatar/css/documentation-topic.b186e79f.css">
<meta name="description" content="Gravatar iOS SDK">
<meta property="og:locale" content="en-US">
<meta property="og:site_name" content="Documentation">
<meta property="og:type" content="website">
<meta property="og:title" content="Gravatar | Documentation">
<meta property="og:description" content="Gravatar iOS SDK">
<meta property="og:url" content="https://automattic.github.io/Gravatar-SDK-iOS/gravatar/documentation/gravatar/">
<meta property="og:image" content="https://automattic.github.io/Gravatar-SDK-iOS/gravatar/developer-og.jpg">
<meta name="twitter:image" content="https://automattic.github.io/Gravatar-SDK-iOS/gravatar/developer-og-twitter.jpg">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:description" content="Gravatar iOS SDK">
<meta name="twitter:title" content="Gravatar | Documentation">
<meta name="twitter:url" content="https://automattic.github.io/Gravatar-SDK-iOS/gravatar/documentation/gravatar/">
<head><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover"><link rel="icon" href="/Gravatar-SDK-iOS/gravatar/favicon.ico"><link rel="mask-icon" href="/Gravatar-SDK-iOS/gravatar/favicon.svg" color="#333333"><title>Gravatar | Documentation</title><script>var baseUrl = "/Gravatar-SDK-iOS/gravatar/"</script><script defer="defer" src="/Gravatar-SDK-iOS/gravatar/js/chunk-vendors.bdb7cbba.js"></script><script defer="defer" src="/Gravatar-SDK-iOS/gravatar/js/index.2871ffbd.js"></script><link href="/Gravatar-SDK-iOS/gravatar/css/index.ff036a9e.css" rel="stylesheet"><link rel="stylesheet" type="text/css" href="/Gravatar-SDK-iOS/gravatar/css/523.e9a069b0.css"><link rel="stylesheet" type="text/css" href="/Gravatar-SDK-iOS/gravatar/css/documentation-topic.b186e79f.css"><meta name="description" content="Gravatar iOS SDK"><meta property="og:locale" content="en-US"><meta property="og:site_name" content="Documentation"><meta property="og:type" content="website"><meta property="og:title" content="Gravatar | Documentation"><meta property="og:description" content="Gravatar iOS SDK"><meta property="og:url" content="https://automattic.github.io/Gravatar-SDK-iOS/gravatar/documentation/gravatar/"><meta property="og:image" content="https://automattic.github.io/Gravatar-SDK-iOS/gravatar/developer-og.jpg"><meta name="twitter:image" content="https://automattic.github.io/Gravatar-SDK-iOS/gravatar/developer-og-twitter.jpg"><meta name="twitter:card" content="summary_large_image"><meta name="twitter:description" content="Gravatar iOS SDK"><meta name="twitter:title" content="Gravatar | Documentation"><meta name="twitter:url" content="https://automattic.github.io/Gravatar-SDK-iOS/gravatar/documentation/gravatar/"></head>

This kind of seems like a bug in the docc process-archive --hosting-base-path option. But I dunno.

Anyway, the simple redirects work great.

andrewdmontgomery commented 1 month ago

I also simplified the build process a little:

  1. Using the scheme Gravatar-Package we can produce both .doccarchive bundles in one build.
  2. Then we process each, including our rewrite of the index.html

This should save us an extra build of the Gravatar module when building GravatarUI.

andrewdmontgomery commented 1 month ago

I'm going to merge this, since the GitHub pages part is working. That way, in a few hours, we should see if we have fixed the SPI documentation.