[Pulp-dev] Pulp3 Docs Builder Issues

[Brian Bouterse]

To have docs to align with the 4 phases of development we would have 4
release streams: 'nightly', 'beta', 'rc', and 'stable'. The url structure
of the site would be something like:

docs.pulpproject.org/en/{x.y}/{beta | nightly | rc}/{tag}/

The {beta | nightly | rc} is literally 'beta' if beta, 'nightly' if
nightly, 'rc' if rc, and that part is left out if it's stable. Travis will
know if {tag} has a 'b' in it then it's a beta publish, 'rc' for release
candidate, and nothing for stable. I believe the nightly one could run via
cron which would know it was run by cron (and therefore nightly).

{tag} would be the tag the release is tagged as e.g. 3.0.1b2, 3.1.3rc1,
3.0.0 (the ga).

The docs pusher in Travis will also ensure that leaving off the tag gives
you the "latest" from that release stream so:
docs.pulpproject.org/en/3.0/beta/ would give you the latest beta and
docs.pulpproject.org/en/3.0/beta/3.0.0b3/ would give you 3.0.0 beta 3.

What about ^ approach?



On Thu, May 10, 2018 at 2:31 PM, David Davis <daviddavis at redhat.com> wrote:

> +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/ecb0806c/attachment.htm>