Open Stack

Resending the below since several projects using ReadTheDocs appear to have
missed this. If your project publishes docs to ReadTheDocs, please follow these
steps to avoid job failures.

On Fri, Aug 03, 2018 at 02:20:40PM +1000, Ian Wienand wrote:
> Hello,
> 
> tl;dr : any projects using the "docs-on-readthedocs" job template
> to trigger a build of their documentation in readthedocs needs to:
> 
>  1) add the "openstackci" user as a maintainer of the RTD project
>  2) generate a webhook integration URL for the project via RTD
>  3) provide the unique webhook ID value in the "rtd_webhook_id" project
>     variable
> 
> See
> 
>  https://docs.openstack.org/infra/openstack-zuul-jobs/project-templates.html#project_template-docs-on-readthedocs
> 
> --
> 
> readthedocs has recently updated their API for triggering a
> documentation build.  In the old API, anyone could POST to a known URL
> for the project and it would trigger a build.  This end-point has
> stopped responding and we now need to use an authenticated webhook to
> trigger documentation builds.
> 
> Since this is only done in the post and release pipelines, projects
> probably haven't had great feedback that current methods are failing
> and this may be a surprise.  To check your publishing, you can go to
> the zuul builds page [1] and filter by your project and the "post"
> pipeline to find recent runs.
> 
> There is now some setup required which can only be undertaken by a
> current maintainer of the RTD project.
> 
> In short; add the "openstackci" user as a maintainer, add a "generic
> webhook" integration to the project, find the last bit of the URL from
> that and put it in the project variable "rtd_webhook_id".
> 
> Luckily OpenStack infra keeps a team of highly skilled digital artists
> on retainer and they have produced a handy visual guide available at
> 
>   https://imgur.com/a/Pp4LH31
> 
> Once the RTD project is setup, you must provide the webhook ID value
> in your project variables.  This will look something like:
> 
>  - project:
>     templates:
>       - docs-on-readthedocs
>       - publish-to-pypi
>     vars:
>       rtd_webhook_id: '12345'
>     check:
>       jobs:
>       ...
> 
> For actual examples; see pbrx [2] which keeps its config in tree, or
> gerrit-dash-creator which has its configuration in project-config [3].
> 
> Happy to help if anyone is having issues, via mail or #openstack-infra
> 
> Thanks!
> 
> -i
> 
> p.s. You don't *have* to use the jobs from the docs-on-readthedocs
> templates and hence add infra as a maintainer; you can setup your own
> credentials with zuul secrets in tree and write your playbooks and
> jobs to use the generic role [4].  We're always happy to discuss any
> concerns.
> 
> [1] https://zuul.openstack.org/builds.html
> [2] https://git.openstack.org/cgit/openstack/pbrx/tree/.zuul.yaml#n17
> [3] https://git.openstack.org/cgit/openstack-infra/project-config/tree/zuul.d/projects.yaml
> [4] https://zuul-ci.org/docs/zuul-jobs/roles.html#role-trigger-readthedocs
> 
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev