Akihiro Motoki amotoki@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.