[Pulp-dev] Pulp3 Docs Builder Issues

[Brian Bouterse]

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.

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/

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20180509/8e2938ce/attachment.htm>