[openstack-dev] What's Up Doc? Aug 13, 2014

Anne Gentle anne at openstack.org
Wed Aug 13 16:00:19 UTC 2014

__In review and merged this past week__

We're cleaning up the Architecture Design Guide continually and I got my
proof copy yesterday. The green cover is lovely as part of the set. The
interior PDF is made the master branch from today and you can get those
print copies rolling!

The landing page is now available at http://docs.openstack.org/arch/ and
you can order a printed copy for yourself. If anyone wants to place an
order for more than 50 copies of any of our books, contact me and I can get
them to you for half price. Go get a dead tree copy today at

The common glossary work continues as well, see
for the spec.

We have review in progress for a templated set of landing pages so the HTML
can be generated more consistently and we don't have to write HTML landing
pages by hand. Thank you Christian! Review at

__High priority doc work__

Thanks to all who participated in the networking guide swarm last week!
Still has a few patches ready for review, and there's also a new spec for
that guide. Let's ensure we're all on the same page (ha!) by reviewing the
patch in docs-specs: https://review.openstack.org/#/c/113597/. The next
plans for the networking guide are to get the spec finished and then to
fill in the outline with tested sections. Shaun is handling the spec and
Nick Chase is coordinating.

__Ongoing doc work__

I've completed the WADL updates that enable removal of WADL from the
book-like deliverables, the API References. Now I need to get the API
References themselves merged.

Next, I'm working on a migration from docbook to RST for the API long-form
documents, which are found here:
http://docs.openstack.org/api/api-specs.html. This work is part of a
blueprint to move API specs to project repositories. [1]

What I'm hearing from Dolph Matthews is that those belong in the
<project>-specs repos, so I'll start there with proposals. I like this
approach for a couple of reasons: 1) it still has publishing available but
2) sets expectations that those are design specs. PTLs, I'll be in touch to
let you know whether you have a document that is affected. So far it's:
Block Storage v2
Compute API v2
Identity API v2.0
Networking API v2.0
Object Storage API v1

The API Reference page is the user-oriented deliverable for APIs:
http://developer.openstack.org/api-ref.html which is still sourced from
WADL in the openstack/api-site repository. I'm investigating replacements
and welcome collaborators.

__New incoming doc requests__

None, our focus is on the Networking Guide, API doc work, the Architecture
Guide readiness, and always the backlog of doc bugs and DocImpact.

__Doc tools updates__

We'll use a static site generator for the content in the
openstack-manuals/www directory that builds our landing pages. It's Jinja2 (
http://jinja.pocoo.org/, already listed in the global requirements).

__Other doc news__

We're holding a Doc Bug Day Tuesday September 9th. Please join in during
your timezone or work all 24 hours!

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140813/71611bb2/attachment.html>

More information about the OpenStack-dev mailing list