doc build check on every pull request

doc build check on every pull request

[Alfredo Deza]

Yesterday the pull request that fixed all warnings and errors for the
docs build was merged [0]. The docs build was in such bad shape that
whole sections wouldn't even render, and several multiple links were
non-existent (references to the source of links were broken).

The docs build has been mostly hidden, only updating the contents of
docs.ceph.com when a branch changes. Since the build was not set to
refuse updating on errors or warnings, it appeared as if everything
was building fine.

To prevent this situation in the future, and to ensure docs are
building correctly, a "doc build check" has been added [1] that will
run on every pull request. This check just builds docs and complains
if it is unable to build because of an error or a warning (it doesn't
publish the html)

The check is triggered automatically and can be re-triggered by either
new commits to the PR, a rebase (followed by a force-push), or by
using the following comment in the PR:

    jenkins test docs

To actually get a build that will render html and publish them in a
publicly accessible place, the previous ad-hoc has changed, and it can
only be triggered by a comment on the PR:

    jenkins render docs

If successful, a comment with a link will be added to the PR.


TL;DR: Docs were severely broken, everything is fixed now, and every
PR now has a 'docs check' that prevents warnings and errors from
getting in.


[0] https://github.com/ceph/ceph/pull/17025
[1] https://github.com/ceph/ceph-build/pull/834