feat: github action to integrate/publish endo and agoric-sdk reference docs too #1038
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,86 @@ | ||
| name: Build and Deploy documentation site | ||
|
|
||
| # This workflow is a customized workflow to deploy docs site to Cloudflare | ||
| # The reason we can no longer use Cloudflare's git integration to deploy docs | ||
| # site anymore is that Cloudflare's git integration would only check out | ||
| # documentation repo, whereas we need to check out both `endojs/endo` and | ||
| # `agoric/agoric-sdk` repo to build the docs site. | ||
|
|
||
| on: | ||
| # If it's a push to production branch, Cloudflare wrangler will deploy it as a | ||
| # production deployment | ||
| # The production branch for documentation project on Cloudflare is configured | ||
| # to be `main` | ||
| push: | ||
| branches: | ||
| - main | ||
| # If it's a push to a non-production branch, Cloudflare wrangler will deploy | ||
| # it as a preview deployment | ||
| pull_request: | ||
| branches: | ||
| - "*" | ||
|
|
||
| jobs: | ||
| build-and-deploy: | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - name: Checkout | ||
| uses: actions/checkout@v4 | ||
|
|
||
| - name: Checkout Endo | ||
| uses: actions/checkout@v4 | ||
| with: | ||
| repository: endojs/endo | ||
| path: endo | ||
|
|
||
| - name: Build Endo docs | ||
| run: | | ||
| cd endo | ||
| yarn install | ||
| yarn docs:markdown-for-agoric-documentation-repo | ||
|
|
||
| - name: Move Endo docs into main/reference | ||
| run: mv endo/api-docs main/reference/endo | ||
|
|
||
| - name: Checkout agoric-sdk | ||
| uses: actions/checkout@v4 | ||
| with: | ||
| repository: agoric/agoric-sdk | ||
| path: agoric-sdk | ||
|
|
||
| - name: Build agoric-sdk docs | ||
| run: | | ||
| cd agoric-sdk | ||
| yarn install | ||
| yarn build | ||
| yarn docs:markdown-for-agoric-documentation-repo | ||
|
|
||
| - name: Move agoric-sdk docs into main/reference | ||
| run: mv agoric-sdk/api-docs main/reference/agoric-sdk | ||
|
|
||
| - name: Build Doc site | ||
| run: | | ||
| yarn install | ||
| yarn docs:build-cf | ||
|
|
||
| - name: Publish to Cloudflare Pages | ||
| id: publish-to-cloudflare-pages | ||
| uses: cloudflare/wrangler-action@v3 | ||
| with: | ||
| apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} | ||
| # Cloudflare account ID is safe to be public | ||
| # Ref: https://github.com/cloudflare/wrangler-legacy/issues/209#issuecomment-541654484 | ||
| accountId: 0c4635effffcd7f36d1b9f0425a4367a | ||
| command: pages deploy --project-name=documentation dist/ | ||
|
|
||
| - name: Comment with preview URL | ||
| if: github.event_name == 'pull_request' | ||
| uses: actions/github-script@v7 | ||
| with: | ||
| script: | | ||
| github.rest.issues.createComment({ | ||
| issue_number: context.issue.number, | ||
| owner: context.repo.owner, | ||
| repo: context.repo.repo, | ||
| body: 'Cloudflare Pages Preview URL: ${{ steps.publish-to-cloudflare-pages.outputs.deployment-url }}' | ||
| }) | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I wonder about using submodules.
It would be nice to be able to get snippets from dapp-agoric-basics, for example.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah I considered it but in my past experience I've only been frustrated about needing to update the hashes for submodules and make git commits. That said, there's not really a good solution whenever we are "orchestrating" multiple repos.
I'm happy to give it another try if there's some submodule-fu I'm missing though.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe the submodule friction is a good thing?
Looks like this workflow is checking out HEAD of the other two repos, but that's not what people can use. I propose that the docs reflect what's in Mainnet. To do that requires a PR on this repo to specify the the branch or tag in the other repos. Expressing that as a git submodule makes sense and it sounds like it would obviate the need to define this additional workflow.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There's some appeal to that, but then how to we make progress on generated reference docs?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The reference docs from each repo can publish anywhere. But this PR is about docs.agoric.com, right? Shouldn't that URL only show you what's in Mainnet?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
again, yes, there's some appeal to that, but running typedoc on the mainnet version of our code yields mostly garbage. So should the generated reference docs on dogs.agoric.com be garbage until our fixes to the jsdoc in agoric-sdk make it to mainnet?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Running typedoc on the mainnet version of the code won't work at all, in fact, will it?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm not proposing that. I'm speaking to whether this repo sources from HEAD or a git submodule. My claim is that sourcing HEAD of agoric-sdk is untenable and so it shouldn't be how this PR is implemented. IIUC, there's no need for a new workflow if the reop used git submodules. Given that we need some way to specify a tag of the source repos, I propose that be how this is implemented.
What tag/version of the other repos to source, I think can change over time. I agree that u13 would be unworkable. Probably same for u14. But maybe u15 can get the docs improvements that have been going into master. Again, independent of my request that the repos are sourced by a tag instead of HEAD.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
ok. yes, that's pretty much what I'm thinking.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This discussion is helpful, I'll look into submodules