Open Stack

On Mon, 2019-09-02 at 15:31 -0400, Doug Hellmann wrote:
> > On Sep 2, 2019, at 3:07 AM, Akihiro Motoki <amotoki at gmail.com> wrote:

[snip]

> > 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.

Unfortunately when we tried to implement this we found that virtually
every project we looked at required _some_ amount of tweaks just to
build, let alone look sensible. This was certainly true of the big
service projects (nova, neutron, cinder, ...) which all ran afoul of a
bug [1] in the Sphinx LaTeX builder. Given the issues with previous
approach, such as the inability to easily reproduce locally and the
general "hackiness" of the thing, along with the fact that we now had
to submit changes against projects anyway, a collective decision was
made [2] to drop that plan and persue the 'pdfdocs' tox target
approach.

If we're concerned about the difficulty of closing this out this cycle,
I'd be in favour of just limiting our scope. IMO, the service projects
are the ones that would benefit most from PDF documentation. These are
the things people actually use and they tend to have the most complete
documentation. Libraries can be self-documenting (yes, I know), in so
far as once can use introspection, existing code examples, and the
'help' built-in to piece together what information they need. We should
aim to close that gap long-term, but for now requiring modifications to
ensure we have _some_ PDFs sounds a lot better than requiring no
modifications and having no PDFs.

Cheers,
Stephen

[1] https://github.com/sphinx-doc/sphinx/issues/3099
[2] http://eavesdrop.openstack.org/irclogs/%23openstack-doc/%23openstack-doc.2019-08-21.log.html#t2019-08-21T13:19:01

> > 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.