This repository has been archived by the owner on Mar 5, 2023. It is now read-only.
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Setup CircleCI for previewing documentation changes
When submitting a PR with changes to the documentation, it would be useful to give the reviewer a way to easily see the results of the changes in the built HTML documentation so that they do not need to build the documentation themselves. Presently, this is usually done by: (1) adding screenshots highlighting the changes to the reviewer, or (2) temporarily hosting the built documentation somewhere. For (1), screenshots may not paint a complete picture of the impact of the changes (e.g. how the changes would fit into the "visual feel" of the whole website), and so a reviewer might need the *whole* website in order to give a good assessment of the changes. On the other hand, (2) requires quite a bit of effort on the PR author's part, and there is always the concern that the hosted website may not be kept updated with the actual changes in the PR. So, we need a solution that builds the PR just like AppVeyor and Travis CI does, but stores the built documentation and hosts it somewhere for reviewers to look at. Something like AppVeyor's build artifacts feature. However, while AppVeyor does allow us to store build artifacts, it does not serve the hosted artifacts with the correct MIME type. Visitors to those files will simply be prompted by their web browser to download the file. Travis CI does not support storing build artifacts, requiring them to be uploaded to another service such as Amazon S3. As such, we will need to find another way. CircleCI[1] is a popular CI service that does provide what we want. Our builds can upload build artifacts, and CircleCI will serve them with the correct MIME type, allowing reviewers to easily browse the built documentation files via their web browser. So, let's add a CircleCI config file to our repo telling CircleCI how to build our documentation, and store it as a build artifact. Reviewers can then view the built documentation by navigating to the build job page, clicking on the "Artifacts" tab and then clicking on the file they want to view. Why not run tests as well? Well, there is a slight problem: CircleCI's free plan only gives us 1500 minutes of build time, and our full build + tests presently take around 3 minutes to run (and might increase in the future as more system tests are added). So, considering the fact that we will setup CircleCI to run on all our PRs, and some developers might prefer to use our CIs rather than running tests locally on their own computers, this 1500 minutes limit might be problematic for us. As such, for now, we'll just configure CircleCI to only build our documentation, so that builds complete much faster (around 30s). We have Travis CI to run our tests, anyway. [1] https://circleci.com/
- Loading branch information