Migration to New Web Design¶

Alternatives¶

Rather than use RST/Sphinx for the new design, we could migrate to markdown/Jekyll which is what the prototype design is already using. The OpenStack ecosystem currently supports Python systems like Sphinx and oslosphinx is available with a theme already.

We could get rid of DocBook completely for all books rather than the phased approach. I don’t think that we have the time to do that in a six-month release, so I’m proposing a phased approach.

Assignee(s)¶

Primary assignee:

annegentle

Other contributors:

jagerandi loquacities klevenstein dhellman

Work Items¶

Research:

January 2015 - Investigate how to publish PDF files within this new design. - Investigate using index.rst collections across repos for new deliverable assembly. This is not a required task for the migration, but will certainly help with information architecture going forward towards “every page is page one” rather than book-like deliverables. (jaegerandi)

Frameworks:

January: Create a taxonomy for suggested tags as part of the Conventions wiki page (klevenstein, loquacities)

DONE January 15, 2015: Create jinja2 templates from Jekyll designs for:

• landing page and search (fifieldt)

DONE February 20, 2015: Create Sphinx template from Jekyll design for:

• content pages (annegentle)

DONE February: Replace static www jinja templates in openstack-manuals with new design

Proof of concept with content:

February 15, 2015: Migrate DocBook to RST for these books in this priority order:

• End User Guide
• Admin User Guide

Tracking on wiki page: https://wiki.openstack.org/wiki/Documentation/Migrate

February 28, 2015: Update our build infrastructure so that Sphinx is used for publishing these documents:

• End User Guide
• Admin User Guide

February 20, 2015: Test templates across browsers to ensure parity with design:

• Chrome on Ubuntu, Fedora, Mac, Windows
• Firefox on Ubuntu, Fedora, Mac, Windows

March 2015: Test translation toolchain. Ying Chun Guo (Daisy) has agreed to investigate.

DONE February 15, 2015: Update oslosphinx to have new openstackdocs theme: Currently the theme name is “openstack.” Reviewing the plan with Doug Hellman, we can either keep the openstack theme and start one named “openstackdocs” or update the openstack theme to be the new design. I prefer to name a new one “openstackdocs” so that the current openstack theme which can indicate when a project’s doc is incubated remains.

DONE Updated to add: looking at the information architecture of the header, it looks like it’s best to have an openstack docs theme that doesn’t necessarily live in oslosphinx. Oslosphinx is used for http://specs.openstack.org, http://docs.openstack.org/infra/system-config, http://governance.openstack.org for example, and http://docs.openstack.org/infra/system-config has modified the header so that it wouldn’t match the other sites. As a result, the plan is to keep the oslosphinx theme with oslosphinx and create a theme in a separate repo named openstackdocsthemes for application to all content published to http://docs.openstack.org.

March (after proof-of-concept and CI is complete): Migrate DocBook to RST for these books in this priority order:

• Cloud Administrator Guide
• Virtual Machine Image Guide
• High Availability Guide
• API Quick Start Guide

March: Once migrated, apply new openstackdocstheme template to these repos and deliverables:

openstack-manuals:

• End User Guide
• Admin User Guide
• Cloud Administrator Guide
• Virtual Machine Image Guide

api-site:

• API Quick Start Guide

ha-guide:

• High Availability Guide

March: Remind projects to update their theme for /developer/ docs for:

• nova
• neutron
• glance
• keystone
• ceilometer
• cinder
• heat
• horizon
• ironic
• sahara
• swift
• trove