[Pulp-dev] Pulp3 Docs Builder Issues

[Dennis Kliban]

On Wed, May 9, 2018 at 1:37 PM, Brian Bouterse <bbouters at redhat.com> wrote:

> We have several problems w/ the Pulp3 docs currently, in decreasing order
> of severity.
>
> 1. We don't have docs per beta, we only have nightly docs [0]. This is a
> problem because during the beta cycle, when we make a backwards
> incompatible change in core's documentation, e.g. merging RQ work, plugins
> can't point there users to the core documentation that pairs wit the
> version of core they tested against. For example if we had core docs for
> beta1, beta2, beta3 ... and pulp_ansible was tested against beta2 only,
> pulp_ansible users should be able to browse the core docs at version beta
> 2. We currently can't do that.
>
> 2. The docs builder is uber complicated[1][2], strangely overlays
> content[3] from pulp-ci, and is still shared with pulp2. This is a
> hold-over from the pulp2 docs builders and we never cleaned them up. This
> has cost us some time recently.
>
> 3. The docs builder is on Jenkins which is not community accessible.
>
> I think we should address this soon, but we need some ideas/discussion
> first.
>
> I've thought of two ideas: move to Read The Docs or Move to Travis. After
> looking into it, RTD is a non-starter AIUI because RTD won't be able to
> install and start all of the services necessary like Travis can.
>
> So to move to Travis we could: Enable a conditional publish so that any
> tag which publishes a build to PyPI also publishes the built docs to
> docs.pulpproject.org/ Additionally, we could configure Travis to publish
> with each merged commit as well so we would have continuous docs.
>
>
+1


> I want to check in on the urls. We need Travis to be able to build it from
> the tag or branch info. Would the url be like:
>
> https://docs.pulpproject.org/en/3.0/beta/3/
>
> Or like:
>
> https://docs.pulpproject.org/en/3.0/beta/3.0.0b3/
>
>
I prefer the latter URL.


> Feedback and ideas are welcome. After some discussion I can incorporate
> all the ideas into a Redmine ticket.
>




>
> -Brian
>
>
> [0]: http://docs.pulpproject.org/en/3.0/nightly/
> [1]: https://github.com/pulp/pulp-ci/blob/master/ci/jjb/jobs/docs
> .yaml#L72-L180
> [2]: https://github.com/pulp/pulp-ci/blob/master/ci/docs-builder.py
> [3]: https://github.com/pulp/pulp-ci/tree/master/ci/docs
>
> _______________________________________________
> Pulp-dev mailing list
> Pulp-dev at redhat.com
> https://www.redhat.com/mailman/listinfo/pulp-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20180510/cef399a8/attachment.htm>