[Pulp-dev] Pulp3 Docs Builder Issues

[David Davis]

+1 to moving to Travis. This fits in with the push-to-PyPI stuff I think.

What does the 'beta' come from in the URL and what would the URLs for say a
tag like 3.0.1 look like?


David

On Thu, May 10, 2018 at 8:29 AM, Dennis Kliban <dkliban at redhat.com> wrote:

> 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
>>
>>
>
> _______________________________________________
> 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/c1f05385/attachment.htm>