Open Stack

Akihiro Motoki <amotoki at gmail.com> writes:

> Hi,
>
> I have a couple of general questions on PDF community goal.
>
> What is the criteria of completing the PDF community goal?
> Is it okay if we publish a PDF deliverable anyway?
>
> During working on it, I hit the following questions.
> We already reached Train-2 milestone, so I think it is the time to clarify
> the detail criteria of completing the community goal.
>
> - Where should the generated PDF file to be located and What is the
> recommended PDF file name?
>   <top directory>/<repository-name>.pdf? index.pdf? Any path and any
> file is okay?

The job will run the sphinx instructions to build PDFs, and then copy
them from build/latex (or build/pdf, I can't remember) into the
build/html directory so they are published as part of the project's
series-specific documentation set.

Project teams should not add anything to their HTML documentation build
to move, rename, etc. the PDF files. That will all be done by the job
changes Stephen has been developing.

Project teams should ensure there is exactly 1 PDF file being built and
that it has a meaningful name. That could be ${repository_name}.pdf as
you suggest, but it could be something else, for now.

> - Do we create a link to the PDF file from index.html (per-project top page)?
>   If needed, perhaps this would be a thing covered by openstackdocstheme.
>   Otherwise, how can normal consumers know PDF documents?

Not yet. We should be able to do that automatically through the theme by
looking at the latex build parameters. If we do it in the theme, rather
than having projects add link content to their builds, we can ensure
that all projects have the link in a consistent location in their docs
pages with 1 patch. If you want to work on that, it would be good, but
it isn't part of the goal.

> - Which repositories need to provide PDF version of documents?
>   My understanding (amotoki) is that repositories with
> 'publish-openstack-docs-pti' should publish PDF doc. right?

Yes, all repositories that follow the documentation PTI.

> - Do we need PDF version of release notes?
> - Do we need PDF version of API reference?

The goal is focused on publishing the content of the doc/source
directory in each repository. There is no need to deal with release
notes or the API reference. We may work on those later, but not for this
goal.

> I see no coordination efforts recently and am afraid that individual
> projects cannot decide whether patches to their repositories are okay
> to merge.

The goal champions have been on vacation. Have a bit of patience,
please. :-)

In the mean time, if there are questions about specific patches, please
raise those here on the mailing list.

The most important thing to accomplish is to ensure that one PDF builds
*at all* from the content in doc/source in each repo. The goal was
purposefully scoped to this one task to allow teams to focus on getting
successful PDF builds from their content, because we weren't sure what
issues we might encounter. We can come back around later and improve the
experience of consuming the PDFs but there is no point in making a bunch
of decisions about how to do that until we know we have the files to
publish.

-- 
Doug