Do people really use GitHub artifacts for documentation?

[Quedlinbug]

I have not used them before, but they only last 90 days at most for public repositories. Do you have to set up a process to run the action again if you don't make changes to the relevant branch in that time period?

[Karl]

For documentation, you generate it, then commit it to a separate branch (example). Then you have GitHub pages serve the contents of that branch. The branch contents won't go away, of course.

Artifacts are generally not used for documentation, I don't think. What I use them for is in CI, I'll generate a log with verbose test information, and I'll upload that as an artifact. Then if the tests fail for some reason, I can inspect the log to better understand what happened.

[Quedlinbug]

@Karl

Artifacts are generally not used for documentation, I don't think.

Thanks. These were some of the first hits when researching, and they both do this, but don't mention automatic expiration.

Deploying DocC with GitHub Actions

DocC Tutorial for Swift: Automating Publishing With GitHub Actions

Edit: This is also what GitHub itself tells you to do.

[Karl]

Curious. They do mention deploying to an orphaned branch, but then use an artifact when automating with GHA.

Perhaps deployed artifacts are immune from the retention limit, so both approaches work?

[jrose (Jordan Rose)]

Or the action is set to run nightly, so it’s always “fresh” even if nothing has changed.

Or they have releases more frequently than every 90 days, and don’t realize there’s going to be a problem.

[Quedlinbug]

@Karl

For documentation, you generate it, then commit it to a separate branch (example).

Is there a practical solution for doing this locally? Or is the lack thereof why anyone would use GitHub Actions? It seems to me that running a script when committing locally would be a better idea than having to use runners, but I don't know how to do that yet.

I found this, which I think would also be a fine time to run the local "action", but I think after-commit still makes the most sense?

How to run a Build-Phase script when building a standalone Swift Package in Xcode?

Hi everyone, I'm trying to learn SPM by making a simple standalone Swift Package with Xcode 11. So far so good I'm now trying to add a Build Phase script to execute SwiftLint when I run my Package's unit-tests locally in Xcode. While reading the SPM documentation, i found that many of the Xcode concepts I'm familiar with can be described in the Package.swift manifest (e.g. targets, products, build-settings, build-configurations...). I found nothing about Schemes in the documen…

[taylorswift]

@Karl

For documentation, you generate it, then commit it to a separate branch (example ). Then you have GitHub pages serve the contents of that branch. The branch contents won't go away, of course.

i’m not an expert on git, but i’m curious what the impact of this on repo weight is? i feel like constantly checking-in a large number of frequently-changing generated files is going to very rapidly “age” the repository and make it difficult to use the package with SwiftPM, which currently performs a deep clone of all package repositories.

i mention this because years ago, i stored a large number of generated files in the swift-png repository which changed frequently and caused it to become very slow to use with SwiftPM today. many other ecosystem packages (e.g. swift-collections) have a similar problem and there are few remedies short of rewriting the git history, which is a nonstarter if the project has more than one contributor.

[Quedlinbug]

@taylorswift

rewriting the git history, which is a nonstarter if the project has more than one contributor.

My understanding is that an artifact is equivalent to this: a 1-commit branch that only gets "force pushed". Is it different? If not, then using actions doesn't solve anything, other than if you're like me and don't know how to script the equivalent local commands yet.

[Karl]

@Quedlinbug

Is there a practical solution for doing this locally? Or is the lack thereof why anyone would use GitHub Actions? It seems to me that running a script when committing locally would be a better idea than having to use runners, but I don't know how to do that yet.

You can use git checkout --orphan

--orphan <new-branch>

Create a new unborn branch, named <new-branch>, started from <start-point> and switch to it. The first commit made on this new branch will have no parents and it will be the root of a new history totally disconnected from all the other branches and commits.

The index and the working tree are adjusted as if you had previously run git checkout <start-point>. This allows you to start a new history that records a set of paths similar to <start-point> by easily running git commit -a to make the root commit.

@taylorswift

i’m not an expert on git, but i’m curious what the impact of this on repo weight is? i feel like constantly checking-in a large number of frequently-changing generated files is going to very rapidly “age” the repository and make it difficult to use the package with SwiftPM

Orphaned branches have no history. The branch and all of its history is entirely replaced on every update.

This can lead to inaccessible commits, but git gc can clean them up. Git will do it automatically according to... some heuristics.

---

Looking at the example from the first article @Quedlinbug linked to: GitHub - AgoraIO-Community/VideoUIKit-iOS: Swift package and CocoaPod to simply integrate Agora Video Calling or Live Video Streaming to your iOS or macOS app with just a few lines of code.

It appears that:

• There is no gh-pages branch, it is just deployed via an action
• The last "Deploy DocC" action was 10 months ago, and its artifact are indeed listed as expired and cannot be downloaded from the action report
• But the deployment to GH pages from those artifacts is still live -- the docs are still available

On the one hand, that could be seen as an advantage: the generated docs are not part of the repository at all, so cloners won't download them. On the other hand, it doesn't seem possible to inspect the deployed files at all, which I'm not entirely comfortable with.

Storing the documentation on a branch is also handy for providing versioned documentation. Otherwise you'll need to build docs for every version on every deployment, or find somewhere else to store them.

Both approaches seem viable.

[ethankusters]

@Quedlinbug

Is there a practical solution for doing this locally? Or is the lack thereof why anyone would use GitHub Actions? It seems to me that running a script when committing locally would be a better idea than having to use runners, but I don't know how to do that yet.

I'm not sure if this is exactly what you're looking for, but the Swift-DocC Plugin's documentation has instructions for how to manually publish to GitHub Pages: Documentation.

You could also look at the plugin's script for publishing its own docs: swift-docc-plugin/bin/update-gh-pages-documentation-site at main · apple/swift-docc-plugin · GitHub.

[Joseph_Heck]

@Quedlinbug you're welcome to borrow/replicate how we're doing this in the Automerge-swift project. Because of a lingering bug with extracting symbols from a binary, we're building the documentation and stashing it into a branch with a script, extracting the symbols manually with an additional build step, and then turning around and hosting this content on GitHub pages for our API documentation.

So to answer your question - yes, we're definitely using GitHub pages to host our docs. We don't rebuild nightly there, only on release (and that makes it a manual process), but that's working nicely for us.

automerge/automerge-swift/blob/main/scripts/build-ghpages-docs.sh

In essence, it's a similar pattern (and older, so there's likely options that aren't strictly needed any longer) to what docc-plugin provides, we just couldn't use that because of the lingering issue. (related issues: Issue with target which have binaryTarget dependency · Issue #80 · apple/swift-docc-plugin · GitHub, No symbols are extracted when generating documentation (w/ the CLI) while the package uses a local XCFramework reference · Issue #52 · apple/swift-docc-plugin · GitHub, & PackagePlugin's PackageManager.getSymbolGraph does not support binaryTarget · Issue #7580 · apple/swift-package-manager · GitHub)