Jump to: navigation, search

Difference between revisions of "Documentation/Migrate"

(End User Guide Migration)
Line 44: Line 44:
 
| section_dashboard_access || Anne Gentle || https://review.openstack.org/151289 || In Progress
 
| section_dashboard_access || Anne Gentle || https://review.openstack.org/151289 || In Progress
 
|-
 
|-
| Example || Example || Example || Example
+
| configure_access_and_security_for_instances || Anne Gentle || local || In Progress
 +
|-
 +
| create_and_manage_databases || Anne Gentle || local || In Progress
 +
|-
 +
| create_and_manage_networks || Anne Gentle || local || In Progress
 +
|-
 +
| create_and_manage_object_containers || Anne Gentle || local || In Progress
 +
|-
 +
| create_and_manage_volumes || Anne Gentle || local || In Progress
 
|}
 
|}
  

Revision as of 23:31, 30 January 2015

Doc Migration from DocBook to RST Overview

Many of the API reference documents were meant for the contributor developer to know what was going into an API. So, the history of that document was forged as a specification. As projects beyond swift and nova were added, projects made similar documents. They're output to HTML at http://docs.openstack.org/api/api-specs.html. However, as we now have a <project>-specs repo, it makes sense to move to those repos. In that move, also it makes sense to migrate to RST rather than DocBook/WADL.

We are also migrating the End User Guide and Admin User Guide to RST. Feel free to sign up for a chapter in the section below.

Migration Conventions

Follow the existing existing markup conventions for RST.

Follow the existing file name conventions.

When in doubt, use simpler markup. This guidance means revise the text to not use tables, and avoid cross-references that are difficult to maintain.

Use :ref: when doing cross references so that you don't have to have the exact title. This means you will have to add markup to create anchors, such as:

.. _dashboard-project-tab:

Please use the existing XML:Ids if possible for these cross references.

Store the figures in a /figures/ directory with the deliverable itself.

If the conversion outputs Note as a heading, change it to .. note::.


End User Guide Migration

First, get a local copy of the End User Guide from openstack-manuals. Create a branch to work within.

Next, either use the process documented on this wiki page or your own methods with pandoc (http://johnmacfarlane.net/pandoc/try/) to convert from DocBook to RST. Pick any chapter or section and look for errors in the automation, then manually clean up. Once you have cleaned up the RST, build it within playground-user-guide by running tox -echeckbuild or if you already have Sphinx installed, run sphinx-build doc/playground-user-guide/source/ doc/playground-user-guide/build/html from within openstack-manuals. This will apply the oslosphinx theme currently.

Sign up below for a chapter, then create a patch with RST in doc/playground-user-guide/source for others to review. Once the patch merges, change the Status from In Review to Merged.

Chapter/Section Name Patch URL Status
section_dashboard_access_and_security.rst Andreas Jaeger https://review.openstack.org/#/c/142437/ Merged
section_dashboard_access Anne Gentle https://review.openstack.org/151289 In Progress
configure_access_and_security_for_instances Anne Gentle local In Progress
create_and_manage_databases Anne Gentle local In Progress
create_and_manage_networks Anne Gentle local In Progress
create_and_manage_object_containers Anne Gentle local In Progress
create_and_manage_volumes Anne Gentle local In Progress

Admin User Guide Migration

Sign up below for a chapter, then create a patch with RST in doc/playground-user-guide/source for others to review.

Chapter/Section Name Patch URL Status
Example Example Example Example
Example Example Example Example

Doc Migration Plan

The Juno projects where this document needs to migrate to a specification are: nova (compute-api) v2, v3 swift (object-api) v1 glance (image-api) v1, v1.1, v2 keystone (identity-api) v2.0, v3 neutron (netconn-api) v1.0, v2.0 cinder (volume-api) v1.0, v2.0

Juno projects that have this type of document in a separate <service>-api repo are: trove (trove)

Juno projects that do not provide this type of prose-based spec for their API are: ceilometer heat sahara

Incubating projects, this information is just a heads-up so you know how we're thinking about API documentation going forward. ironic zaqar (marconi) barbican designate

I'm going to do the migration work with pandoc and propose the patch to the project's repo. Be on the lookout for those patches.

Doc Migration Steps

Open docbook book file in Oxygen.

Choose Document > Transformation > Configure Transformation Scenario(s).

Select DocBook XHTML - Chunk.

Click Apply associated (1).

Within the /out/xhtml-chunks/ directory that's generated, run the following script:

for i in *.xhtml
do
  # Convert from XHTML to RST
  file_name=${i%.*l}.rst
  pandoc -s -t rst $i -o $file_name
  sed -i -e '4,16d' $file_name 
  sed -i -e '/+--------------------------+$/,$d' $file_name
  sed -i -e '$d' $file_name
  sed -i -e '$d' $file_name

  # Rename file to second line of new RST content, but lowercase and
  # all non-alphanumeric chars renamed to underscores
  real_file_name=$(sed 's/[^a-zA-Z0-9\-]/_/g;2q;d' $file_name | awk '{print tolower($0)}').rst
  mv $file_name $real_file_name
  # Replace all cross-refs to xhtml files to renamed rst files
  sed -i '' -e "s/\<$i/fixmefixmefixme/g" *.rst
#  sed -i '' -e "s/\ fixmefixmefixme.*\`__//g" *.rst
done

Clean up where the fredfredfred is output, it indicates where a cross-reference cannot exist any longer.

Clean up tables where the pandoc conversion just outputs paragraphs.

Remove numbering from Example titles and Table titles.

Rename chapter_ files and ensure they are titled to match the contents of the file, such as "Networking API 2.0 Overview" to networking_api_2.0_overview" for example.

Remove "programlisting" "screen" and "literallayout" from .. code:: lines.