Generate previews of documentation when documenters open a pull request on Github

Bug #1903476 reported by Jane Sandberg
10
This bug affects 2 people
Affects Status Importance Assigned to Milestone
Evergreen
Fix Released
Wishlist
Unassigned

Bug Description

I mentioned this in a recent developers meeting (http://irc.evergreen-ils.org/evergreen/2020-10-06#i_461692) and at the hack-a-way.

Basically, setting up a working antora build environment presents a barrier for documenters. We'd like to have a Continuous Integration server generate preview versions of the documentation, so that documenters can see what their proposed changes look like after the docs have been generated.

Branch forthcoming that:
* Uses docker and docker-compose to create a container that generates the antora documentation
* Includes a CircleCI configuration that uses the docker process every time somebody pushes a commit or opens a pull request
* Uses the moxci notifier (https://github.com/moxci/moxci) to notify the person who opened the pull request about the built version of the documentation.

Revision history for this message
Jane Sandberg (sandbergja) wrote :

Pull request here: user/sandbergja/lp1903476_circleci_docs_building

Some info about CircleCI's free tier for open source organizations: https://circleci.com/open-source/

To test the docker part only:

1) Cherry-pick this commit into your own github repository
that includes the antora documentation
2) Install docker and docker-compose
3) Run this command: `docker-compose up -d`
4) Notice that the documentation is generated into the
docs-compiled directory

To test the whole integration:

1) In CircleCI, "follow" your github repository that
includes the antora documentation and this commit
2) In your CircleCI Project Settings, go to
Environment Variables.
3) Enter your Circle CI API Token as CIRCLE_TOKEN,
and Github API Token as GITHUB_TOKEN
4) In the `Advanced Settings` page of your project's
settings, enable `Only build pull requests`
5) Open a pull request that makes a change to the
antora documentation.
6) Wait for the "All checks have passed" notification.
Click "Show all checks". One of them should be a link
to your documentation.
7) Ideally, there will also be a comment automatically
added to your pull request.

tags: added: pullrequest
Revision history for this message
Andrea Neiman (aneiman) wrote :

Big +1 from me on this! I will see about testing this later this week.

Changed in evergreen:
status: New → Confirmed
importance: Undecided → Wishlist
Revision history for this message
Jane Sandberg (sandbergja) wrote :

Removing pullrequest for now. I suspect we could use Github Actions to do this, removing the need for us to use a third party service.

tags: removed: pullrequest
Revision history for this message
Jane Sandberg (sandbergja) wrote :

Here is a branch that uses Github Actions, rather than some third party solution. It turned out to be quite simple, just one file and no configuration steps needed.

Here is the new branch: user/sandbergja/lp1903476_build_docs_with_github_actions

Here is a link: https://git.evergreen-ils.org/?p=working/Evergreen.git;a=shortlog;h=refs/heads/user/sandbergja/lp1903476_build_docs_with_github_actions

Here are the testing steps:
1. Use the Github Web site to fork the Evergreen repository.
2. Take the .github/workflows/docs.yml file from my user/sandbergja/lp1903476_build_docs_with_github_actions branch. Add it to any branch of your fork of the Evergreen repository.
3. Click on the Actions tab of your fork in the Github Web site.
4. Click on the most recent run (at the top of the list).
5. When the build process is done (should take 3-4 minutes), download and unzip the artifact that appears at the bottom of the screen. Open index.html in your browser. Confirm that the docs built properly.
6. On the same branch, make some changes to the documentation in the docs/modules directory.
7. Repeat steps 3-5. Confirm that your changes are reflected in the new artifact.

tags: added: pullrequest
Revision history for this message
Jane Sandberg (sandbergja) wrote :

A quick note that I just force-pushed a small (but fundamental) change to my branch. Previously, pull-requests were not listed as an event that triggers the docs build, which defeats the whole point of the ticket.

Now, pull-requests are listed as an event that triggers a docs build.

I should also mention: I have this enabled in a branch on my fork of Github. So, you can also feel free to make pull requests against the build-docs-in-github-actions branch in the sandbergja/Evergreen repo to kick the tires of this.

Revision history for this message
Jason Boyer (jboyer) wrote :

I checked this out and it looks good, so it's in master now. I also added a followup commit to limit a rebuild to when a push or PR affects files under docs/ and removed the perl setup action since the ubuntu-latest environment already includes[1] perl 5.30. Thanks Jane!

[1] https://github.com/actions/virtual-environments/blob/main/images/linux/Ubuntu2004-Readme.md

Changed in evergreen:
status: Confirmed → Fix Committed
Revision history for this message
Jason Boyer (jboyer) wrote :

Note, since this is something that only happens on github.com and not locally installed software I'll go ahead and mark this Fix Released since it's already "released" on GH.

Changed in evergreen:
status: Fix Committed → Fix Released
Revision history for this message
Jane Sandberg (sandbergja) wrote :

Great follow-up refinements. Thanks, Jason!

To post a comment you must log in.
This report contains Public information  
Everyone can see this information.

Other bug subscribers

Remote bug watches

Bug watches keep track of this bug in other bug trackers.