Documentation/Migrate
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.
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/fredfredfred/g" *.rst # sed -i '' -e "s/\ fredfredfred.*\`__//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.