[Pulp-dev] Pulp3 Docs Builder Issues

[Dana Walker]

This seems like a reasonable approach.  +1

Dana Walker

Associate Software Engineer

Red Hat

<https://www.redhat.com>
<https://red.ht/sig>

On Thu, May 10, 2018 at 4:35 PM, Brian Bouterse <bbouters at redhat.com> wrote:

> 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
> <http://docs.pulpproject.org/en/%7Bx.y%7D/%7Bbeta> | 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
>>>
>>>
>>
>
> _______________________________________________
> 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/20180514/d6926f67/attachment.htm>