openstack-doc-core team mailing list archive

[Anne Gentle <anne@xxxxxxxxxxxxx>]

tl;dr: Walking through the next update to the Maven plugin[1], I'm trying
to uncover what work needs to be done for going to 1.6.2+ across the
openstack-manuals repo, the api-site repo, and all the <restservice>-api
repos. There are 24 pom.xml files to be updated and CI jobs that correspond.

Explanation:
1.6.2+ renames the output files purposefully. We have been relying on
postProcess to rename the files, but postProcess is not needed for renaming
and placing PDF or image files with 1.6.2+.

As a walkthrough for a few guides, here's what I think has to happen:
Pre-reqs:
Any bugs in output need to be fixed? How about the highlightSource one[2]?
What else needs testing?

Tasks:
1. All xml source files need to have role="html" and role="fo" removed from
the imageobject elements. Originally I thought this change can't happen
until the pom.xml points to the new 1.6.2+ plugin, but I learned the
imageobject scaling is turned off in HTML output. So as long as the source
image isn't too large, placement and scaling should be ok in HTML and PDF.
This patch resized some images: https://review.openstack.org/1901
2. All pom.xml files need to have <postProcess> removed, the TOC code
changed, and possibly change the highlight code. Also if you set
<sectionAutolabel>0</sectionAutolabel>, you no longer need to set
<sectionLabelIncludesComponentLabel>0</sectionLabelIncludesComponentLabel>.
This work has to be done across eight repos with reviews for each.
3. With the new file names in hand, the CI jobs need to be changed to pick
up and rename the files. The files are now built to
target/docbkx/webhelp/<bk-file-name>-external. So for example, the
openstack-admin-manual-compute job needs to copy all files in
bk-compute-adminguide-external/ to
docs.openstack.org/$release-name/openstack-compute/admin/. This job is in
https://github.com/openstack-infra/config in
modules/openstack_project/files/jenkins_job_builder/config. The good news
is, it's all files in OpenStack CI. One patch might do it.
4. After patching the CI config files you have to retrigger all the doc
build jobs by patching the eight repos.

Side note, possible scope creep: as long as we're having to update all
these jobs anyway, should we duplicate the job to also copy (scp) to
docs-draft.openstack.org?

I'm going through the compute admin guide, the install/deploy guides, and
the compute-api guide to test. You are welcome to help out! I'm sending
this note to let you know the scope of the changes, make sure you all have
the background explanation, and to see if I've missed any crucial aspect of
this upgrade. I'll keep testing but wanted to get a sanity check.

Questions, just ask!
Thanks,
Anne
1. https://github.com/rackspace/clouddocs-maven-plugin
2. https://bugs.launchpad.net/openstack-manuals/+bug/1095412

Scope:
Here's a listing of all affected pom.xml files and build job files:

openstack-manuals, three branches, essex, folsom, master
 openstack-admin-manual-compute (1) essex, folsom, master
 openstack-admin-manual-netconn (1) essex, folsom, master
 openstack-admin-manual-object (1) essex, folsom, master
 openstack-cli-guide (1) folsom, master
 openstack-glossary (1) folsom, master
 openstack-install-deploy-guide-apt-fedora (1, shared with install/deploy
ubuntu) essex, folsom, master
 openstack-install-deploy-guide-ubuntu (shared with above) essex, folsom,
master
 openstack-basic-install (1) folsom, master
 openstack-ha (1) folsom, master
 openstack-ops (not yet building)

api-site (no branches for API docs)
 openstack-api-programming guide (1)
 api-quick-start (1)
 api-reference (1)

compute-api (3)
image-api (2)
object-api (1)
netconn-api (2)
volume-api (1)
identity-api (2)

total: 23 (ops) +14 (api) =37 books build with jobs, 24 pom.xml files get
built