Build the doc with CircleCI?

[emmanuelle]

At the moment, when a change is made to the documentation, the persons who are reviewing the PR have to (or should :-)) fetch the corresponding branch and build the doc on their machine. We could maybe use CircleCI and configure it to build the doc, so that it would be possible to see the new doc online, without having to build it locally.

What do you think?

[sciunto]

I think there are pro and cons. Clearly, it will make our life easier for PR where new features with documentation are added because very often screenshots are not attached. On the other way, it will take time to setup and to maintain just because we don't have a hand on these servers and we will depend on them if them change anything in the configuration. For travis for example, we have to spend quite a lot of time to my taste to maintain configurations just because we do not always have the right versions or so.

[soupault]

I agree, that would be a nice feature to have.
Basically speaking, we would like to have a fair web-deployed copy of documentation tree for each existing PR. That's a huge overhead.

Reasonable alternative is to enable artifacts creation for Travis (quick googling has indicated that there is such an option https://blog.travis-ci.com/2012-12-18-travis-artifacts/. In any case, at least AppVeyor has it), where on each commit a PR is not just being built, but also the outcomes of the building process are stored. This way, one could download automatically built copy of skimage and evaluate corresponding .html doc files. That is already much faster than manual building. To reduce the overhead for storing artifacts (I believe there is a limit of available storage for free accounts), we could save only doc folders as CI artifacts.
The most complex thing from my point of view is how do we select PRs of interest. At very rough estimate, only 20% of recent PRs introduce some changes to the documentation tree. Maybe we could use some of neat GitHub bots (for example, see rust-lang/cargo#3039 (comment) and tensorflow/tensorflow#3960 (comment)) to detect if a PR changes anything in doc folder and trigger the corresponding option for Travis. This will, obviously, require some work to be implemented.

Finally, we have to developed a process to remove old/stored artifacts (applicable both for AppVeyor, Travis or even our website). Currently, I have no ideas how to make this work.

[soupault]

Whoa! There is one more neat bot -> rust-lang/cargo#3039 (comment) . This one can be triggered to automatically build and merge PRs. If we decide on this solution, I believe that it is not so hard to write a customized bot for our needs.

[stefanv]

We should also check in with @matthew-brett who has experimented with
similar bot software

[soupault]

See the comments in #3483.

[soupault]

I would like to revisit this issue.

I can change the Azure Pipelines confugiration to build the docs and upload them to some cloud storage. Not sure if GitHub Terms of Use allow that, but some (potentially private) repository could be used for such purposes.

To avoid building the docs for every PR, it is possible to set some filters in Azure, for example, based on the PR caption (DOC: ... - build, * - do not build). Unfortunately, GitHub does not render .html files, so one will need to download the affected page/example. That will be not perfectly convenient, but still will bring a notable improvement to our workflow.

Any opinions on this implementation?

[hmaarrfk]

https://htmlpreview.github.io/?https:/

[grlee77]

closed by #4881