Thanks to visit codestin.com
Credit goes to github.com

Skip to content

ci: Publish haddocks to GitHub Pages #183

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 4 commits into from
Mar 14, 2025
Merged

ci: Publish haddocks to GitHub Pages #183

merged 4 commits into from
Mar 14, 2025

Conversation

langston-barrett
Copy link
Contributor

In between full Hackage releases, it would be nice to be able to read haddocks for the latest commit on the default branch. This PR builds the haddocks in CI, and publishes them to GitHub Pages.

In more detail, this PR breaks the cabal haddock step out of the testing job into a separate job for the sake of controlling concurrency and permissions, while reusing the cache from the build step to build the haddocks.

I'd be completetly fine with hearing that we don't think that the maintenance is worth it, I mostly wanted to prototype this for use on our repos that we don't publish to Hackage (e.g., Macaw) and just figured I'd make a PR in case others thought this would be useful.

If we did want to merge this, we would want to temporarily disable the if stanza that only deploys on the master branch, to try it out.

@langston-barrett
ci: Publish Haddocks to GitHub Pages
5577d16 
In between full Hackage releases, it would be nice to be able to read
haddocks for the latest commit on the default branch. This commit builds
the haddocks in CI, and publishes them to GitHub Pages.

In more detail, this commit breaks the `cabal haddock` step out of the
testing job into a separate job for the sake of controlling concurrency
and permissions, while reusing the cache from the build step to build
the haddocks.
@langston-barrett langston-barrett self-assigned this Mar 13, 2025
@langston-barrett langston-barrett marked this pull request as ready for review March 13, 2025 21:44
kquick
kquick approved these changes Mar 13, 2025
View reviewed changes
Copy link
Member

@kquick kquick left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This overall publishing should be fine in general. I don't know how fully useful this will be since it will only be the docs for this package and so I expect cross references won't work. Another thought is that if there are space constraints on gh-pages (although I'm not aware of any, and even with our larger projects I suspect the size of generated docs is rather minimal).

This will only provide the latest master version of the docs.

A couple of comments, one geared towards minimizing the support overhead.

@kquick
Copy link
Member

kquick commented Mar 13, 2025

Umm... there were comments, where did they go, Github?! I'll try to recreate after my meeting.

kquick
kquick reviewed Mar 13, 2025
View reviewed changes
kquick
kquick reviewed Mar 13, 2025
View reviewed changes
@kquick
Copy link
Member

kquick commented Mar 13, 2025

OK, comments added.

@langston-barrett
Copy link
Contributor Author

Ah, it appears that Github Pages needs to be enabled in the repository settings. @kquick Do you have sufficient permissions to make that happen?

@langston-barrett
Copy link
Contributor Author

Ah, now it appears that I can't do a test deployment on this branch:

Branch "lb/ci-haddock" is not allowed to deploy to github-pages due to environment protection rules.

@kquick do you want to try temporarily changing the rules in the settings, or would you rather try merging this? It will probably work...

@langston-barrett langston-barrett mentioned this pull request Mar 14, 2025
Open
@langston-barrett
Copy link
Contributor Author

Hmm...

Fetching artifact metadata for "github-pages" in this workflow run
Found 2 artifact(s)
Error: Fetching artifact metadata failed. Is githubstatus.com reporting issues with API requests, Pages, or Actions? Please re-run the deployment at a later time.
Error: Error: Multiple artifacts named "github-pages" were unexpectedly found for this workflow run. Artifact count is 2.
    at getArtifactMetadata (/home/runner/work/_actions/actions/deploy-pages/v4/src/internal/api-client.js:89:1)
    at processTicksAndRejections (node:internal/process/task_queues:95:5)
    at Deployment.create (/home/runner/work/_actions/actions/deploy-pages/v4/src/internal/deployment.js:66:1)
    at main (/home/runner/work/_actions/actions/deploy-pages/v4/src/index.js:30:1)
Error: Error: Multiple artifacts named "github-pages" were unexpectedly found for this workflow run. Artifact count is 2.

FWIW, githubstatus.com is not reporting any issues.

I wonder if there is a way to give a more specific name to the artifact, perhaps including the workflow/job run ID?

@langston-barrett
Copy link
Contributor Author

Oh, this appears to be an issue specifically related to retrying CI builds with these actions:

I will try adding a new commit instead.

@langston-barrett
Copy link
Contributor Author

It works! 🚀 http://galoisinc.github.io/parameterized-utils/

@langston-barrett
ci: Rename concurrency group from haddock to pages
9baa199 
...as the latter is actually the resource being protected.
@langston-barrett
Copy link
Contributor Author

I don't know how fully useful this will be since it will only be the docs for this package and so I expect cross references won't work.

Current status appears to be that identifiers for e.g. base are hyperlinked, but to bad destinations. Example: Applicative. There may be a cabal haddock flag we can use to fix this.

@langston-barrett
Copy link
Contributor Author

Another thought is that if there are space constraints on gh-pages (although I'm not aware of any, and even with our larger projects I suspect the size of generated docs is rather minimal).

GitHub publishes some documentation on usage limits. It's not clear to me from those docs whether or how much our organization is charged for the storage, but as you say, the docs are likely reasonably small. The artifact .zip is 265K.

This will only provide the latest master version of the docs.

Indeed.

@langston-barrett
Copy link
Contributor Author

Unfortunately, --haddock-quickjump and --haddock-hyperlink-source both require changes to the build plan (resulting in rebuilding dependencies), so I'll just leave those off for now even though they would be nice to have.

@langston-barrett
Copy link
Contributor Author

I've got the links to other packages going to hackage.haskell.org now.

@langston-barrett
Copy link
Contributor Author

FWIW, these deployment errors seen on this PR seem to have to do with competition between the push and pull_request triggers. It seems we run two CI builds for each push to a branch with an associated PR. This won't be a problem when this is landed, because doc pushes will only happen on main.

@langston-barrett langston-barrett merged commit 00d54c8 into master Mar 14, 2025
20 checks passed
@langston-barrett langston-barrett deleted the lb/ci-haddock branch March 14, 2025 16:58
@langston-barrett langston-barrett mentioned this pull request Mar 19, 2025
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@kquick kquick kquick approved these changes

@RyanGlScott RyanGlScott Awaiting requested review from RyanGlScott

Assignees

@langston-barrett langston-barrett

Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@langston-barrett @kquick