Open Stack

Progress
--------

After more than 580 patches, the migration is moving along very
well. We do still have quite a few repositories that haven't been
updated [1], though, so please help us trim that list. It's really
important that we finish the migration before we create stable/pike
branches to avoid having to backport the content.

Recovering Old Content
----------------------

We have started working on a tool [2] to recover "old" versions of
docs associated with tagged releases and stable branches by moving
it out of the /developer directory on the web server into the new
publishing structure. We will be coordinating with the infra team
over the next couple of weeks to move the content. I will send
another announcement when that is done.

The Theme Is Not Enough
-----------------------

Several project teams have landed the patch to move from oslosphinx
to openstackdocstheme. Please remember that that is only one of
several steps in the migration, and is not sufficient to complete
the work. The new templating system for docs.openstack.org relies
on a YAML file with booleans indicating when a project has specific
types of content (installation instructions, API reference and/or
guide, configuration reference, etc.). The flag allows the template
to insert a pre-defined URL matching the new documentation layout,
and a gate job verifies that the content exists before the link is
allowed. That means that if you have content published somewhere
other than where it is expected, it *will not be linked* from the
landing pages on docs.openstack.org.

In-Tree API Docs
----------------

We have had one or two projects who already have in-tree API
documentation that was not being published to developer.openstack.org
ask about having their links added to docs.openstack.org. That is
in process [3].

Theme Rendering Issues
----------------------

A few folks have also raised issues with the appearance of the docs
after moving to openstackdocs theme. Good, you're reading! Please
files bugs [4] (or patches [5]) for these issues. The theme is still
being updated, and there will be lots of opportunities to address any
problems.

Doug

[1] http://lists.openstack.org/pipermail/openstack-dev/2017-July/119483.html
[2] https://review.openstack.org/481710
[3] https://review.openstack.org/482188
[4] https://launchpad.net/openstack-manuals
[5] http://git.openstack.org/cgit/openstack/openstackdocstheme