Open Stack

> On Sep 3, 2019, at 5:54 AM, Stephen Finucane <sfinucan at redhat.com> wrote:
> 
> 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.

We wanted to avoid making a bunch of the same changes to projects just to
add the PDF building instructions. If the *content* of a project’s documentation
needs work, that’s different. We should make those changes.

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