On Sep 2, 2019, at 3:07 AM, Akihiro Motoki <amotoki@gmail.com> wrote:
On Mon, Sep 2, 2019 at 1:12 PM Thomas Bechtold <tbechtold@suse.com> wrote:
Hi,
On 8/27/19 7:58 AM, Akihiro Motoki wrote:
[...]
How to get started ------------------
- "How to get started" section in the PDF goal etherpad [1] explains the minimum steps. You can find useful examples there too.
This is a bit confusing because the goal[1] mentions that there should be no extra tox target declared for the gate job. But the etherpad explains that there should be a new tox target[2].
So do we need a new tox target in the project repo? Or is that optional and just for local testing?
The new tox target in the project repo is required now. The PDF doc will be generated only when the "pdf-docs" tox target does exists.
When the goal is defined the docs team thought the doc gate job can handle the PDF build without extra tox env and zuul job configuration. However, during implementing the zuul job support it turns out at least a new tox env or an extra zuul job configuration is required in each project to make the docs job fail when PDF build failure is detected. As a result, we changes the approach and the new tox target is now required in each project repo.
The whole point of structuring the goal the way we did was that we do not want to update every single repo this cycle so we could roll out PDF building transparently. We said we would allow the job to pass even if the PDF build failed, because this was phase 1 of making all of this work. The plan was to 1. extend the current job to make PDF building optional; 2. examine the results to see how many repos need significant work; 3. add a feature flag via a setting somewhere in the repo to control whether the job fails if PDFs cannot be built. That avoids a second doc job running in parallel, and still allows us to roll out the PDF build requirement over time when we have enough information to do so.
Perhaps we need to update the description of the goal definition document.
I don’t think it’s a good idea to change the scope of the goal at this point in the release cycle.
Thanks, Akihiro
Cheers,
Tom
[1] https://governance.openstack.org/tc/goals/selected/train/pdf-doc-generation.... [2] https://etherpad.openstack.org/p/train-pdf-support-goal
- To build PDF docs locally, you need to install LaTex related packages. See "To test locally" in the etherpad [1]. - If you hit problems during PDF build, check the common problems etherpad [2]. We are collecting knowledges there. - If you have questions, feel free to ask #openstack-doc IRC channel.
Also Please sign up your name to "Project volunteers" in [1].
Useful links ------------
[1] https://etherpad.openstack.org/p/train-pdf-support-goal [2] https://etherpad.openstack.org/p/pdf-goal-train-common-problems [3] Ongoing reviews: https://review.opendev.org/#/q/topic:build-pdf-docs+(status:open+OR+status:m...)
Thanks, Akihiro Motoki (amotoki)