Generate previews of documentation when documenters open a pull request on Github
Affects | Status | Importance | Assigned to | Milestone | |
---|---|---|---|---|---|
Evergreen |
Fix Released
|
Wishlist
|
Unassigned |
Bug Description
I mentioned this in a recent developers meeting (http://
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:/
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.