Jump to: navigation, search

Difference between revisions of "Documentation/Migrate"

m (Cloud Admin Guide Migration)
(API Reference Plan)
 
(540 intermediate revisions by 34 users not shown)
Line 1: Line 1:
 
== Doc Migration from DocBook to RST Overview ==
 
== Doc Migration from DocBook to RST Overview ==
 
 
We are currently migrating the End User Guide and Admin User Guide to RST. Feel free to sign up for a chapter in the section below. We plan to enable more migrations with the End User Guide and Admin User Guide as our first phase.
 
 
 
Previously, we migrated the <service>-api repos from DocBook to RST. These were API reference documents that 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.
 
Previously, we migrated the <service>-api repos from DocBook to RST. These were API reference documents that 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.
  
 
== Migration Conventions ==
 
== Migration Conventions ==
  
Follow the existing [[Documentation/Markup_conventions|existing markup conventions for RST]].  
+
Follow the RST markup conventions in the [http://docs.openstack.org/contributor-guide/rst-conv.html OpenStack Documentation Contributor Guide] .  
 
 
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.
 
  
 
=== Headings ===
 
=== Headings ===
Line 70: Line 64:
  
 
List of bugs or missing features for the Sphinx template, openstackdocstheme: https://bugs.launchpad.net/openstack-manuals/+bugs?field.tag=openstackdocstheme
 
List of bugs or missing features for the Sphinx template, openstackdocstheme: https://bugs.launchpad.net/openstack-manuals/+bugs?field.tag=openstackdocstheme
 
How to get numbered list continuation to work when you have a table in a step?
 
 
How to get numbered list continuation to work when you have a bulleted list between list items?
 
 
How do we address converting files with conditional or audience profiling ?
 
 
How to get get embedded .. note: directives to work between numbered list items?
 
  
 
Can you have line breaks in something with inline semantic markup like :guilabel: at the end of the line? For example:
 
Can you have line breaks in something with inline semantic markup like :guilabel: at the end of the line? For example:
Line 89: Line 75:
 
That line is longer than 79 characters, so Attachments`. must be on the second line, but when you do that, the HTML output is incorrect.
 
That line is longer than 79 characters, so Attachments`. must be on the second line, but when you do that, the HTML output is incorrect.
  
== Migration How To ==
+
Since RST documents impose a 79 character limit when building files in .rst format. When tables exceed that limit, a list table role can help create content in a new table without exceeding the character limit. The issue is when a table is generated by an OpenStack service, and returned as a result of a command. These tables are constructed with +, -, and | characters. The table created by a list table role has solid lines forming rows, columns, and cells. The content is similar, however users might be surprised by a table with solid lines rather than a table built with +, -, and | characters.
 +
 
 +
Large scale content inside tables.
 +
 
 +
When building tables with a list table role, some items that appear inside the table cells might exceed the 79 character limit. Is there a solution to recreating this large scale content in a table such that it does not affect the character limit?
 +
 
 +
The :orphan: role and references.
  
'''Note:''' If you don't want to use tox, install these prereqs locally: pip install sphinx; pip install openstackdocstheme and then switch to the directory containing a conf.py and run sphinx-build /path/to/source/ path/to/build/ to get html output by default.
+
Files with an :orphan: role at the top of the file, not included in the toc tree, will not link to another file when the :ref: role is used to link to the file from a different file. Is there a solution to this linking issue?
  
Because Sphinx builds have dependent requirements it is best to work with in a virtual environment. Fortunately the openstack-manuals project already has tox set up so that you can create a virtualenv that contains the required dependencies. To use it, do this on a Mac or Ubuntu machine with Python and pip already installed:
+
Pandoc conversion problems.
  
Clone the openstack-manuals repo.
+
When converting files with Pandoc, some entries in the .xml file will not convert accurately. Procedure titles and sub section titles will not parse correctly, and will be deleted from the converted document. Pandoc also removes procedure numbering. Currently, the solution is to compare the complete .rst file to the built .xml version, and check the headings, subheadings, and procedure numbers to make sure they are correct, and line up with original. This is an issue that could also be discussed.
  
Change directories into openstack-manuals.
+
*Contact details for RST issues that we can't solve:
 +
** Author: David Goodger
 +
** Contact: docutils-develop@lists.sourceforge.net
  
Run this:
+
== Migration How To ==
  
tox -e py27
+
'''Note:''' If you don't want to use tox, install these prereqs locally: pip install sphinx; pip install openstackdocstheme and then switch to the directory containing a conf.py and run sphinx-build /path/to/source/ path/to/build/ to get html output by default.
  
When you get a congratulations message, run this:
+
Because Sphinx builds have dependent requirements it is best to work with in a virtual environment. Fortunately the openstack-manuals project already has tox set up so that you can create a virtualenv that contains the required dependencies. To use it, do this on a Mac or Ubuntu machine with Python and pip already installed:
  
 +
# Clone the openstack-manuals repository.
 +
# Change directories into openstack-manuals.
 +
# Run this:
 +
#:  <pre>tox -e py27</pre>
 +
# When you get a congratulations message, run this:
 
Mac/Ubuntu:
 
Mac/Ubuntu:
 
+
<pre>source .tox/py27/bin/activate</pre>
source .tox/py27/bin/activate
 
  
 
Windows:
 
Windows:
 
+
<pre> source .tox/py27/Scripts/activate</pre>
source .tox/py27/Scripts/activate
 
  
 
Your prompt should now have (py27) as a preface.
 
Your prompt should now have (py27) as a preface.
Line 123: Line 120:
 
When the build is finished, you can open doc/playground-user-guide/build/html/index.html to view the resulting output.
 
When the build is finished, you can open doc/playground-user-guide/build/html/index.html to view the resulting output.
  
== End User Guide Migration ==
+
===Migration Using Oxygen===
 +
# 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:
 +
#:  <pre>
 +
#::  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<pre><nowiki>
 +
#::  # 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</pre>
 +
# Clean up where the fixmefixmefixme 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.
 +
# When commiting conversion patches, include the related blueprint in your commit message. For example:
 +
#:  <pre>
 +
#::  Convert ch_compute_focus.xml to RST
 +
#::  Implements: blueprint archguide-mitaka-rst</pre>
  
First, get a local copy of the End User Guide from openstack-manuals. Create a branch to work within.
+
===Migration Using a Text Editor===
 +
# Install [http://pandoc.org/installing.html pandoc].
 +
# Update your openstack-manuals master branch, and create a branch.
 +
# Run the pandoc command to convert the .xml file to .rst. For example:
 +
#:  <pre>pandoc -f docbook -t rst -s ch_compute_focus.xml -o compute-focus.rst</pre>
 +
# Move converted files to the <guide>/source folder.
 +
# Rename converted RST 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.
 +
# Pandoc has its quirks, so check all the content has been migrated from the source file.
 +
# Use a text editor to complete the following tasks:
 +
## Clean up tables where the pandoc conversion just outputs paragraphs.
 +
## Remove numbering from Example titles and Table titles.
 +
## Remove "programlisting" "screen" and "literallayout" from .. code:: lines.
 +
## Check the converted RST file follow conventions described in the [http://docs.openstack.org/contributor-guide/rst-conv.html OpenStack Documentation Contributor Guide]
 +
# Build the guide locally, to check for errors:
 +
#:  <pre>tox -e docs</pre>
 +
# Commit your changes, including the related blueprint in your commit message. For example:
 +
#:  <pre>
 +
#::  Convert ch_compute_focus.xml to RST
 +
#::  Implements: blueprint archguide-mitaka-rst</pre>
  
These files should use this markup in the first two lines to ensure they are only output in the user guide version:
+
== Doc Migration Plan ==
<pre>
 
<nowiki>
 
.. meta::
 
    :scope: user_only
 
</nowiki>
 
</pre>
 
  
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.  
+
For the Mitaka release, we migrated the Configuration Reference Guide and the Architecture Design Guide. Refer to the [http://specs.openstack.org/openstack/docs-specs/index.html detailed specification] for details.
  
Sign up below for a chapter, then create a patch with RST in doc/playground-user-guide/source for others to review. Use the xml:id from the DocBook file for the RST file name. Once the patch merges, change the Status from In Review to Merged.
+
=== API Reference Plan ===
  
{| class="wikitable"
+
See [http://docs.openstack.org/contributor-guide/api-guides.html http://docs.openstack.org/contributor-guide/api-guides.html] for explanation of the process. Anne has already preprocessed the files, so the other migration steps on this wiki page are not needed at all.
|-
 
! Chapter/Section (old filename) !! Chapter/Section (new filename) !! Name !! Patch URL !! Status
 
|-
 
| xxx || section_dashboard_access_and_security.rst || Andreas Jaeger || https://review.openstack.org/#/c/142437/ || Merged
 
|-
 
| xxx || section_dashboard_access || Anne Gentle || https://review.openstack.org/151289 || Merged
 
|-
 
| xxx || launching_instances_using_dashboard || Anne Gentle || https://review.openstack.org/#/c/170617/ || Merged
 
|-
 
| xxx || upload_manage_images_using_dashboard || Anne Gentle || https://review.openstack.org/#/c/170593/ || Merged
 
|-
 
| section_dashboard_databases.xml || dashboard_databases || Anne Gentle || https://review.openstack.org/#/c/151846/ || Merged
 
|-
 
| xxx || dashboard_create_networks || Anne Gentle || https://review.openstack.org/#/c/152582/ || Merged
 
|-
 
| xxx || dashboard_manage_containers || Anne Gentle || https://review.openstack.org/#/c/153349/ || Merged
 
|-
 
| xxx || dashboard_manage_volumes || Anne Gentle || https://review.openstack.org/#/c/153577 || Merged
 
|-
 
| section_dashboard_stacks.xml || dashboard_stacks.rst || Olena Logvinova || https://review.openstack.org/168863 || Merged
 
|-
 
| section_cli_trove.xml || trove-manage-db.rst || Laurel Michaels || https://review.openstack.org/#/c/156087/ || Merged
 
|-
 
| section_cli_trove.xml || create_db.rst || Laurel Michaels || https://review.openstack.org/156266/ || Merged
 
|-
 
| section_cli_trove.xml || backup_db.rst || Laurel Michaels || https://review.openstack.org/#/c/164791/ || Merged
 
|-
 
| section_cli_trove.xml || backup_db_incremental.rst || Laurel Michaels || https://review.openstack.org/#/c/167649/ || Merged
 
|-
 
| section_cli_trove.xml || manage_db_config.rst || Laurel Michaels || https://review.openstack.org/#/c/169002/ || Merged
 
|-
 
| section_cli_trove.xml || set_up_replication.rst || Laurel Michaels || https://review.openstack.org/#/c/170560/ || Merged
 
|-
 
| section_cli_trove.xml || set_up_clustering.rst || Laurel Michaels || https://review.openstack.org/#/c/170734/ || Merged
 
|-
 
| ch_cli.xml || cli || Karin Levenstein || https://review.openstack.org/#/c/154235/ || Merged
 
|-
 
| section_cli_nova_boot || cli_launch_instances || Karin Levenstein || https://review.openstack.org/#/c/154235/ || Merged
 
|-
 
| ch_sdk.xml || sdk || Darren Chan || https://review.openstack.org/#/c/154412/ || Merged
 
|-
 
| section_sdk_install || sdk_install  || Darren Chan || https://review.openstack.org/#/c/154412/ || Merged
 
|-
 
| section_sdk_authenticate || sdk_authenticate  || Darren Chan || https://review.openstack.org/#/c/154412/ || Merged
 
|-
 
| section_sdk_manage_images.xml || sdk_manage _images || Darren Chan || https://review.openstack.org/#/c/154412/  || Merged
 
|-
 
| section_sdk_configure_instances.xml || sdk_configure _access_security_instances  || Darren Chan || https://review.openstack.org/#/c/154412/  || Merged
 
|-
 
| section_sdk_neutron.xml || sdk_authenticate_networking_endpoint || Darren Chan || https://review.openstack.org/#/c/154412/  || Merged
 
|-
 
| section_sdk_nova.xml || sdk_authenticate_compute_endpoint  || Darren Chan || https://review.openstack.org/#/c/154412/ || Merged
 
|-
 
| section_cli_swift_howto.xml || managing-openstack-object-storage-with-swift-cli  || Erik Wilson || https://review.openstack.org/#/c/165132/ || Merged
 
|-
 
| xxx || cli_create_containers.rst || Erik Wilson || https://review.openstack.org/#/c/165132/ || Merged
 
|-
 
| xxx || cli_swift_manage_access_swift.rst || Erik Wilson || https://review.openstack.org/#/c/165132/ || Merged
 
|-
 
| xxx || cli_swift_manage_objects.rst || Erik Wilson || https://review.openstack.org/#/c/165132/ || Merged
 
|-
 
| section_object-api-env-vars.xml || cli_swift_env-vars.rst || Erik Wilson || https://review.openstack.org/#/c/165132/ || Merged
 
|-
 
| section_object-api-versioning.xml || cli_swift_set-object-versions.rst || Erik Wilson || https://review.openstack.org/#/c/165132/ || Merged
 
|-
 
| section_object-api-response-formats.xml || cli_swift_serialized-response-formats.rst || Erik Wilson || https://review.openstack.org/#/c/165132/ || Merged
 
|-
 
| section_object-api-large-lists.xml || cli_swift_large-lists.rst || Erik Wilson || https://review.openstack.org/#/c/165132/ || Merged
 
|-
 
| section_object-api-pseudo-hier-folders.xml || cli_swift_pseudo-hierarachical-folders-directories.rst || Erik Wilson || https://review.openstack.org/#/c/165132/ || Merged
 
|-
 
| section_object-api-discoverability.xml || cli_swift_discoverability.rst || Erik Wilson || https://review.openstack.org/#/c/165132/ || Merged
 
|-
 
| section_object-api-create-large-objects.xml || cli_swift_large-object-creation.rst || Erik Wilson || https://review.openstack.org/#/c/165132/ || Merged
 
|-
 
| section_object-api-create-large-objects.xml || cli_swift_archive-auto-extract.rst || Erik Wilson || https://review.openstack.org/#/c/165132/ || Merged
 
|-
 
| section_object-api-bulk-delete.xml || cli_swift_bulk-delete.rst || Erik Wilson || https://review.openstack.org/#/c/165132/ || Merged
 
|-
 
| section_object-api-create-website.xml || cli_swift_static-website.rst || Erik Wilson || https://review.openstack.org/#/c/165132/ || Merged
 
|-
 
| section_object-api-cors-headers.xml || sdk_assign_cors_headers || Darren Chan || https://review.openstack.org/#/c/156451/ || Merged
 
|-
 
| section_cli_nova_manage_instances.xml || cli_manage_instances_hosts || Darren Chan || https://review.openstack.org/#/c/157270/|| Merged
 
|-
 
| section_cli_nova_floating_ips.xml || cli_manage_ip_addresses || Darren Chan || https://review.openstack.org/#/c/157270/|| Merged
 
|-
 
| section_cli_nova_resizerebuild.xml || cli_change_the_size_of_your_server || Darren Chan || https://review.openstack.org/#/c/157270/|| Merged
 
|-
 
| section_cli_nova_startstop.xml|| cli_stop_and_start_an_instance || Darren Chan || https://review.openstack.org/#/c/157270/|| Merged
 
|-
 
| section_cli_nova_userdata.xml || cli_provide_user_data_to_instances || Darren Chan || https://review.openstack.org/#/c/157270/ || Merged
 
|-
 
| appendix_a__openstack_command-line_interface_cheat_sheet.xml || cli_quick_start || Anne Gentle || https://review.openstack.org/158142/ || Merged
 
|-
 
| section_object-api-expire-objects.xml || sdk_schedule_objects_for_deletion || Darren Chan || https://review.openstack.org/#/c/158961/ || Merged
 
|-
 
| section_sdk_auth_keystone.xml || sdk_authenticate_against_identity_endpoint || Darren Chan || https://review.openstack.org/#/c/158961/ || Merged
 
|-
 
| section_sdk_auth_glance.xml || sdk_authenticate_against_image_service_endpoint || Darren Chan || https://review.openstack.org/#/c/158961/ || Merged
 
|-
 
| section_sdk_auth_nova.xml || sdk_authenticate_against_compute_endpoint || Darren Chan || https://review.openstack.org/#/c/158961/ || Merged
 
|-
 
| section_sdk_auth_neutron.xml || sdk_authenticate_against_networking_endpoint || Darren Chan || https://review.openstack.org/#/c/158961/ || Merged
 
|-
 
| section_cli_nova_reboot.xml || cli_reboot_an_instance || Darren Chan || https://review.openstack.org/#/c/160578/ || Merged
 
|-
 
| section_cli_nova_terminate.xml || cli_delete_an_instance || Darren Chan || https://review.openstack.org/#/c/160578/ || Merged
 
|-
 
| section_cli_nova_get_console.xml || cli_access_instance_through_a_console || Darren Chan || https://review.openstack.org/#/c/160578/ || Merged
 
|-
 
| section_cli_nova_baremetal.xml || cli_manage_bare_metal_nodes || Darren Chan || https://review.openstack.org/#/c/160578/ || Merged
 
|-
 
| section_cli_nova_search_ip.xml || cli_search_instance_with_ip_address || Darren Chan || https://review.openstack.org/#/c/160578/ || Merged
 
|-
 
| section_cli_nova_migrate_instances.xml || cli_use_snapshots_to_migrate _instances || Darren Chan || https://review.openstack.org/#/c/160578/ || Merged
 
|-
 
| common/section_cli_overview.xml || common/cli_overview || Darren Chan || https://review.openstack.org/#/c/164060/ || Merged
 
|-
 
| common/section_cli_install.xml || common/cli_install_openstack_command_line _clients || Darren Chan || https://review.openstack.org/#/c/167111/ || Merged
 
|-
 
| common/section_cli_version.xml || common/cli_discover_version_number_for _a_client || Darren Chan || https://review.openstack.org/#/c/166075/ || Merged
 
|-
 
| common/section_cli_openrc.xml || common/cli_set_environment_variables_using_openstack_rc || Darren Chan || https://review.openstack.org/#/c/166075/ || Merged
 
|-
 
| common/section_cli_neutron_manage_networks.xml || common/cli_create_and_manage_networks || Darren Chan || https://review.openstack.org/#/c/166075/ || Merged
 
|-
 
| common/section_cli_glance_manage_images.xml || common/cli_manage_images || Darren Chan || https://review.openstack.org/#/c/166075/ || Merged
 
|-
 
| common/section_cli_cinder_manage_volumes.xml || common/cli_manage_volumes || Darren Chan || https://review.openstack.org/#/c/166075/ || Merged
 
|-
 
| common/ch_using_openstack_overview.xml ||  ||  || ||
 
|-
 
| common/section_cli_nova_usage_statistics.xml || common/cli_nova_show_usage_statistic_for_hosts_instances || Darren Chan || https://review.openstack.org/#/c/166085/ || Merged
 
|-
 
| section_cli_nova_configure_instances.xml || cli_nova_configure_access_security_for_instances || Darren Chan || https://review.openstack.org/#/c/168772/ || Merged
 
|-
 
| common/section_cli_nova_boot_from_volume.xml || cli_nova_launch_instance_from_volume || Darren Chan || https://review.openstack.org/#/c/168772/ || Merged
 
|-
 
| hot-guide/*.rst || || Gauvain Pocentek || https://review.openstack.org/#/c/156351/ || Merged
 
|-
 
| section_cli_nova_config-drive.xml || cli_config_drive || Anne Gentle || https://review.openstack.org/#/c/171025/ || Merged
 
|-
 
| section_cli_heat.xml || cli_create_and_manage_stacks || Darren Chan || https://review.openstack.org/#/c/171446/ || Merged
 
|}
 
  
== Admin User Guide Migration ==
+
Sign up below for a service, then download the files from this patch: https://review.openstack.org/#/c/311596/. These will require a lot of cleanup manually but gets them as far as the tools can get them. Also, setup a job to publish data like https://review.openstack.org/312184.
 
 
Sign up below for a chapter, then create a patch with RST in doc/playground-user-guide/source for others to review.  
 
 
 
These files should use this markup in the first two lines to ensure they are only output in the admin version:
 
<pre>
 
<nowiki>
 
.. meta::
 
    :scope: admin_only
 
</nowiki>
 
</pre>
 
  
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
! Chapter/Section (old filename) !! Chapter/Section (new filename) !! Name !! Patch URL !! Status  
+
! Service name !! Service version !! Project !! Name !! Patch URL !! Status  
|-
 
| section_cli_admin_manage_environment.xml || cli_admin_manage_environment.rst || Olga Gusarenko || https://review.openstack.org/#/c/165121 || Merged
 
|-
 
| section_cli_admin_manage_stacks.xml || cli_admin_manage_stacks.rst || Olga Gusarenko || https://review.openstack.org/#/c/165121 || Merged
 
|-
 
| section_cli_cinder_quotas.xml || cli_cinder_quotas.rst || Olga Gusarenko || https://review.openstack.org/#/c/165803 || Merged
 
|-
 
| section_cli_keystone_services.xml || cli_keystone_manage_services.rst || Olga Gusarenko || https://review.openstack.org/#/c/166786 || Merged
 
|-
 
| section_cli_keystone_set_quotas.xml || cli_set_quotas.rst || Olga Gusarenko || https://review.openstack.org/#/c/165803 || Merged
 
|-
 
| section_cli_manage_services.xml || cli_manage_services.rst || Olga Gusarenko || https://review.openstack.org/#/c/166786 || Merged
 
 
|-
 
|-
| section_cli_nova_floating_ips.xml || cli_admin_manage_ip_addresses.rst || Olga Gusarenko || https://review.openstack.org/#/c/168296 || Merged
+
| Compute || v2.|| nova || Sean Dague  || https://review.openstack.org/#/q/status:merged+project:openstack/nova+branch:master+topic:bp/api-ref-in-rst || In progress
 
|-
 
|-
| section_cli_nova_host_servers_migrate.xml || xmlid.rst || Olga Gusarenko || Not used currently or find a proper place for it || Deferred
+
| Identity || v2.|| keystone || Samuel de Medeiros Queiroz  || https://review.openstack.org/#/q/project:openstack/keystone+branch:master+topic:migrate-identity-api-ref || In progress
 
|-
 
|-
| section_cli_nova_manage_flavors || cli_manage_flavors.rst || Olga Gusarenko || https://review.openstack.org/#/c/168797 || In Progress
+
| Identity || v3 (and extensions)  || keystone || Samuel de Medeiros Queiroz  || https://review.openstack.org/#/q/project:openstack/keystone+branch:master+topic:migrate-identity-api-ref  || In progress
 
|-
 
|-
| section_cli_nova_manage_projects_security || nova_cli_manage_projects_security.rst || Anne Gentle || https://review.openstack.org/#/c/156877 || Merged
+
| Bare metal || v1  || ironic || Jim Rollenhagen ||https://review.openstack.org/#/c/312181/ and https://review.openstack.org/312184  || In progress
 
|-
 
|-
| section_cli_nova_migrate.xml || cli_nova_migrate.rst || Maria Zlatkova || https://review.openstack.org/#/c/167178 || Merged
+
| Block Storage || v1  || cinder || Sheel Rana Insaan  || https://review.openstack.org/#/c/312113 || In progress
 
|-
 
|-
| section_cli_nova_services.xml || cli_nova_manage_services.rst || Olga Gusarenko || https://review.openstack.org/#/c/166786 || Merged
+
| Block Storage || v2  || cinder || Sheel Rana Insaan  || https://review.openstack.org/#/c/312113 || In progress
 
|-
 
|-
| section_cli_nova_specify_host.xml || cli_nova_specify_host.rst || Olga Gusarenko || https://review.openstack.org/#/c/168869 || Merged
+
| Clustering || v1  || senlin ||   ||  ||  
 
|-
 
|-
| section_dashboard_admin_manage_flavors.xml || dashboard_manage_flavors.rst || Olena Logvinova || https://review.openstack.org/#/c/167154 || Merged
+
| Data Processing || v1.|| sahara || || Note: has these REST API docs http://docs.openstack.org/developer/sahara/restapi/rest_api_v1.0.html ||  
 
|-
 
|-
| section_dashboard_admin_manage_host_aggregates.xml || dashboard_manage_host_aggregates.rst || Anne Gentle || https://review.openstack.org/163198 || Merged
+
| Database || v1.|| trove || Laurel Michaels  || https://review.openstack.org/#/c/316381  || Needs review, can't build locally
 
|-
 
|-
| section_dashboard_admin_manage_images.xml || dashboard_manage_images.rst || Olena Logvinova || https://review.openstack.org/#/c/167950/2 || Merged
+
| Image || v1  || glance || rosmaita || https://review.openstack.org/#/c/312259/ and https://review.openstack.org/#/c/315191/ || merged
 
|-
 
|-
| section_dashboard_admin_manage_resources.xml || dashboard_manage_resources.rst || Karen Bradshaw || https://review.openstack.org/#/c/165583/ || Merged
+
| Image || v2  || glance || rosmaita || https://review.openstack.org/#/c/332950/ || merged
 
|-
 
|-
| section_dashboard_admin_manage_roles.xml || dashboard_admin_manage_roles.rst || Olena Logvinova || https://review.openstack.org/166241 || Merged
+
| Tasks || v2 || glance || rosmaita || https://review.openstack.org/#/c/333029/ || merged
 
|-
 
|-
| section_dashboard_admin_manage_services.xml || dashboard_manage_services.rst || Karen Bradshaw || https://review.openstack.org/#/c/165486/ || Merged
+
| Metadefs || v2 || glance || rosmaita || https://review.openstack.org/#/c/333031/ || merged
 
|-
 
|-
| section_dashboard_admin_manage_stacks.xml || dashboard_manage_stacks.rst || Olena Logvinova || https://review.openstack.org/#/c/168303 || Merged
+
| Networking || v2.0 (and extensions) || neutron || HenryG, amotoki  || https://review.openstack.org/#/c/314819/ || In progress
 
|-
 
|-
| section_dashboard_admin_set_quotas.xml || dashboard_set_quotas.rst || Karen Bradshaw || https://review.openstack.org/#/c/166306 || Merged
+
| Object Storage || v1  || swift || Anne Gentle  || https://review.openstack.org/312315  || In review
 
|-
 
|-
| section_dashboard_admin_view_cloud_resources.xml || dashboard_view_cloud_resources.rst || Karen Bradshaw || https://review.openstack.org/#/c/165499/ || Merged
+
| Orchestration || v1  || heat || Jay Dobies (jdob)  || https://review.openstack.org/#/c/312712/ and https://review.openstack.org/312726  || Complete :)
 
|-
 
|-
| section_cli_keystone_manage_projects_users_roles.xml || admin_cli_manage_projects_users.rst || Anne Gentle || https://review.openstack.org/#/c/156877/ || Merged
+
| Shared File Systems || v1  || manila || Daniel Gonzalez || https://review.openstack.org/#/c/313874 and https://review.openstack.org/#/c/313875 || Merged
 
|-
 
|-
| section_cli_keystone_manage_projects_users_roles.xml || nova_cli_manage_projects_security.rst || Anne Gentle || https://review.openstack.org/#/c/156877/ || Merged
+
| Shared File Systems || v2  || manila || Daniel Gonzalez || https://review.openstack.org/#/c/313874 and https://review.openstack.org/#/c/313875 || Merged
 
|-
 
|-
| section_dashboard_admin_manage_instances.xml || dashboard_manage_instances.rst || Anne Gentle || https://review.openstack.org/163082 || Merged
+
| Telemetry || v2  || ceilometer || || Note: has these REST API docs http://docs.openstack.org/developer/ceilometer/webapi/v2.html ||  
|-
 
| section_dashboard_admin_manage_volumes.xml || dashboard_manage_volumes.rst || Anne Gentle || https://review.openstack.org/163087 || Merged
 
 
|-
 
|-
| section_cli_swift_analyze_log_files.xml || analyzing-log-files-with-swift-cli.rst || Anne Gentle || https://review.openstack.org/161092 || Merged
 
 
|}
 
|}
  
== Cloud Admin Guide Migration ==
+
=== Operations Guide ===
 
 
Sign up below for a chapter, then create a patch with RST in doc/admin-guide-cloud-rst/source for others to review. While the User Guide Specialty team will be giving the conversion attention, contributions are welcome.
 
 
 
As these conversion patches are part of the User Guide reorganization effort, we'd like them to be linked to the related blueprint.  Do this by adding 'Implements: blueprint reorganise-user-guides' to your commit messages.  This automatically creates a link to the blueprint in the review and also adds a patch link in the blueprint.
 
 
 
Example:
 
<pre><nowiki>
 
  Convert chap_database.xml to RST
 
  
  Implements: blueprint reorganise-user-guides
+
Sign up below for a chapter, then create a patch with RST in doc/ops-guide/source for others to review. Contributions are welcome.
  Change-Id: I12343297fsaf782fd8802478236fds2067eaq127890
+
Please add "Implements: blueprint ops-guide-rst" in the commit message.
</nowiki></pre>
 
  
NOTE: Conversion of the networking sections is currently on hold pending a content audit.
+
'''''Please make sure this book follows [http://chimera.labs.oreilly.com/books/123000000https://review.openstack.org/#/c/292036/0969/ch02.html O'Reilly conventions].'''''
  
 
{| class="wikitable"
 
{| class="wikitable"
Line 377: Line 238:
 
! Chapter/Section (old filename) !! Chapter/Section (new filename) !! Name !! Patch URL !! Status  
 
! Chapter/Section (old filename) !! Chapter/Section (new filename) !! Name !! Patch URL !! Status  
 
|-
 
|-
| ch_identity_mgmt.xml || identity_management.rst || Darren Chan || https://review.openstack.org/#/c/186281/ || Merged
+
| bk_ops_guide.xml ||  ||  ||  ||  
|-
 
| ch_compute.xml || compute.rst || Brian Moss || https://review.openstack.org/#/c/191652/ || Merged
 
|-
 
| ch_orchestration.xml || orchestration.rst || Olena Logvinova || https://review.openstack.org/#/c/189722/ || Merged
 
|-
 
| ch_telemetry.xml || telemetry.rst || Olena Logvinova || https://review.openstack.org/#/c/191140 || Merged
 
|-
 
| ch_database.xml || database.rst || Maria Zlatkova || https://review.openstack.org/#/c/191152 || Merged
 
|-
 
| ch_blockstorage.xml || blockstorage.rst || Maria Zlatkova || https://review.openstack.org/#/c/190151 || Merged
 
|-
 
| ch_dashboard.xml || dashboard.rst || Brian Moss || https://review.openstack.org/#/c/189555/ || Merged
 
|-
 
| common/section_dashboard_customizing.xml || common-rst/dashboard_customizing.rst || Brian Moss || https://review.openstack.org/#/c/189555/ || Merged
 
|-
 
| common/section_dashboard_sessions.xml || dashboard_sessions.rst || Brian Moss || https://review.openstack.org/#/c/189555/ || Merged
 
|-
 
| ch_networking.xml || networking.rst || Alexandra Settle || Link to review || On hold
 
|-
 
| /network/section_networking_adv_features.xml || section_networking_adv_features.rst ||  Alexandra Settle || Link to review || On hold
 
|-
 
| /network/section_networking-adv-config.xml || networking-adv-config.rst ||  Alexandra Settle || Link to review || On hold
 
|-
 
| /network/section_networking_adv_operational_features.xml || networking_adv_operational_features.rst ||  Alexandra Settle || Link to review || On hold
 
|-
 
| /network/section_networking_arch.xml || networking_arch.rst ||  Alexandra Settle || Link to review || On hold
 
|-
 
| /network/section_networking_auth.xml || networking_auth.rst ||  Alexandra Settle || Link to review || On hold
 
|-
 
| /network/section_networking_config-agents.xml || networking_config-agents.rst ||  Alexandra Settle || Link to review || On hold
 
 
|-
 
|-
| /network/section_networking_config-plugins.xml || networking_config-plugins.rst ||  Alexandra Settle || Link to review || On hold
+
| preface_ops.xml || preface_ops.rst ||  venkatamahesh  || https://review.openstack.org/#/c/292071  || Merged
 
|-
 
|-
| /network/section_networking_introduction.xml || networking_introduction.rst ||  Alexandra Settle || Link to review || On hold
+
| part_architecture.xml || part_architecture.rst || venkatamahesh || https://review.openstack.org/#/c/292064  || Merged
 
|-
 
|-
| /network/section_networking_pagination_and_sorting_support.xml || networking_pagination_and_sorting_support.rst || Alexandra Settle || Link to review || On hold
+
| part_operations.xml || operations.rst || KATO Tomoyuki || https://review.openstack.org/#/c/291987/ || Merged
 
|-
 
|-
| /network/section_networking-config-identity.xml || networking-config-identity.rst ||  Alexandra Settle || Link to review || On hold
+
| ch_arch_cloud_controller.xml || ch_arch_cloud_controller.rst ||  venkatamahesh  || https://review.openstack.org/#/c/292061  || Merged
 
|-
 
|-
| /network/section_networking-multi-dhcp-agents.xml || networking-multi-dhcp-agents.rst ||  Alexandra Settle || Link to review || On hold
+
| ch_arch_compute_nodes.xml || ch_arch_compute_nodes.rst || venkatamahesh || https://review.openstack.org/#/c/292059  || Merged
 
|-
 
|-
| /network/section_networking-scenarios.xml || networking-scenarios.rst ||  Alexandra Settle || Link to review || On hold
+
| ch_arch_examples.xml || ch_arch_examples.rst ||  venkatamahesh  ||   https://review.openstack.org/#/c/292052  || Merged
 
|-
 
|-
| /network/section_networking-use.xml || networking-use.rst ||  Alexandra Settle || Link to review || On hold
+
| section_arch_example-neutron.xml || section_arch_example-neutron.rst ||  venkatamahesh  || https://review.openstack.org/#/c/291965  || Merged
 
|-
 
|-
| /common/section_identity-troubleshooting.xml || identity_management.rst (not common content) || Darren Chan || https://review.openstack.org/#/c/189566/ || Merged
+
| section_arch_example-nova.xml || section_arch_example-nova.rst || venkatamahesh  || https://review.openstack.org/#/c/291783  || Merged  
 
|-
 
|-
| /common/section_keystone-concepts-user-management.xml || identity_management.rst || Darren Chan || https://review.openstack.org/#/c/189566/ || Merged
+
| ch_arch_network_design.xml || ch_arch_network_design.rst   || venkatamahesh  || https://review.openstack.org/#/c/291974  || Merged
 
|-
 
|-
| /common/section_keystone-concepts-service-management.xml || identity_management.rst || Darren Chan || https://review.openstack.org/#/c/189566/ || Merged
+
| ch_arch_provision.xml || ch_arch_provision.rst || venkatamahesh  || https://review.openstack.org/#/c/291976  || Merged
 
|-
 
|-
| /common/section_keystone-concepts-group-management.xml || identity_management.rst || Darren Chan || https://review.openstack.org/#/c/189566/ || Merged
+
| ch_arch_scaling.xml || ch_arch_scaling.rst || venkatamahesh  || https://review.openstack.org/#/c/291978  || Merged
 
|-
 
|-
| /common/section_keystone_certificates-for-pki.xml || keystone_certificates_for_pki.rst || Darren Chan || https://review.openstack.org/#/c/193958/ || Merged
+
| ch_arch_storage.xml || ch_arch_storage.rst || venkatamahesh  || https://review.openstack.org/#/c/292007  || Merged
 
|-
 
|-
| /common/section_keystone-ssl-config.xml|| keystone_configure_with_SSL.rst || Darren Chan || https://review.openstack.org/#/c/193958/ || Merged
+
| ch_ops_advanced_configuration.xml || ch_ops_advanced_configuration.rst   || venkatamahesh  || https://review.openstack.org/#/c/292008 || Merged
 
|-
 
|-
| /common/section_keystone-external-auth.xml || keystone_external_authentication.rst || Darren Chan || https://review.openstack.org/#/c/193958/ || Merged
+
| ch_ops_backup_recovery.xml || ch_ops_backup_recovery.rst || venkatamahesh  || https://review.openstack.org/#/c/292011  || Merged
 
|-
 
|-
| /common/section_keystone_config_ldap.xml || keystone_integrate_with_LDAP.rst || Darren Chan || https://review.openstack.org/#/c/194520/ || Merged
+
| ch_ops_customize.xml || ch_ops_customize.rst || venkatamahesh || https://review.openstack.org/#/c/292013  || Merged
 
|-
 
|-
| identity/section_keystone-token-binding.xml || keystone_token-binding.rst || Darren Chan || https://review.openstack.org/#/c/194520/ || Merged
+
| ch_ops_lay_of_land.xml || lay_of_the_land.rst || KATO Tomoyuki || https://review.openstack.org/#/c/291996/ || Merged
 
|-
 
|-
| identity/section_keystone-trusts.xml || keystone_use_trusts.rst || Darren Chan || https://review.openstack.org/#/c/194520/ || Merged
+
| ch_ops_log_monitor.xml || ch_ops_log_monitor.rst || venkatamahesh  || https://review.openstack.org/#/c/292015  || Merged
 
|-
 
|-
| identity/section_caching-layer.xml || keystone_caching_layer.rst || Darren Chan || https://review.openstack.org/#/c/194520/ || Merged
+
| ch_ops_maintenance.xml || ch_ops_maintenance.rst || venkatamahesh  || https://review.openstack.org/#/c/292022  || Merged
 
|-
 
|-
| common/section_keystone_config_ldap-identity.xml || keystone_integrate_identity_backend_ldap.rst || Darren Chan || https://review.openstack.org/#/c/194520/ || Merged
+
| ch_ops_network_troubleshooting.xml || ch_ops_network_troubleshooting.rst || venkatamahesh  || https://review.openstack.org/#/c/292027 || Merged
 
|-
 
|-
| identity/section_keystone_config_ldap-assignments.xml || keystone_integrate_assignment_backend_ldap.rst || Darren Chan || https://review.openstack.org/#/c/194520/ || Merged
+
| ch_ops_projects_users.xml || projects_users.rst || KATO Tomoyuki || https://review.openstack.org/#/c/292002/ || Merged
 
|-
 
|-
| identity/section_keystone_config_ldap-hardening.xml || keystone_secure_identity_to_ldap_backend.rst || Darren Chan || https://review.openstack.org/#/c/194520/ || Merged
+
| ch_ops_resources.xml || ch_ops_resources.rst || venkatamahesh  || https://review.openstack.org/#/c/292033 || Merged
 
|-
 
|-
| section_orchestration-auth-model.xml || orchestration-auth-model.rst || Olena Logvinova || https://review.openstack.org/#/c/192575 || Merged
+
| ch_ops_upgrades.xml || ch_ops_upgrades.rst || venkatamahesh  || https://review.openstack.org/#/c/292035  || Merged
 
|-
 
|-
| section_orchestration-stack-domain-users.xml || orchestration-stack-domain-users.rst || Olena Logvinova || Link to review || In progress
+
| ch_ops_upstream.xml || ch_ops_upstream.rst || venkatamahesh  || https://review.openstack.org/#/c/292036  || Merged
 
|-
 
|-
| ch_objectstorage.xml || objectstorage.rst || Karen Bradshaw || https://review.openstack.org/#/c/189806/ || Merged
+
| ch_ops_user_facing.xml || ch_ops_user_facing.rst || venkatamahesh || https://review.openstack.org/#/c/292050 || Merged
 
|-
 
|-
| common/section_objectstorage-characteristics.xml || objectstorage_characteristics.rst || Karen Bradshaw || https://review.openstack.org/#/c/189806/ || Merged
 
|-
 
| common/section_objectstorage-intro.xml || objectstorage_intro.rst || Karen Bradshaw || https://review.openstack.org/#/c/190598/ || Merged
 
|-
 
| common/section_objectstorage-features.xml || objectstorage_features.rst || Karen Bradshaw || https://review.openstack.org/#/c/190598/ || Merged
 
|-
 
| common/section_objectstorage-components.xml || objectstorage_components.rst || Karen Bradshaw || https://review.openstack.org/#/c/190598/ || Merged
 
|-
 
| section_object-storage-monitoring.xml || object-storage-monitoring.rst || Alexandra Settle || https://review.openstack.org/#/c/190425/5 || Merged
 
|-
 
| section_object-storage-admin.xml || object-storage-admin.rst || Alexandra Settle || https://review.openstack.org/#/c/190425/5 ||Merged
 
|-
 
| section_increase-api-throughput.xml || blockstorage.rst || Maria Zlatkova || https://review.openstack.org/#/c/191788 || Merged
 
|-
 
| /common/section_objectstorage-ringbuilder.xml || objectstorage_ringbuilder.rst || Brian Moss || https://review.openstack.org/#/c/190483/ || Merged
 
|-
 
| /common/section_objectstorage-arch.xml || objectstorage_arch.rst || Brian Moss || https://review.openstack.org/#/c/190483/ || Merged
 
|-
 
| /common/section_objectstorage-replication.xml || objectstorage_replication.rst || Brian Moss || https://review.openstack.org/#/c/190483/ || Merged
 
|-
 
| /common/section_objectstorage-account-reaper.xml || objectstorage_account_reaper.rst || Brian Moss || https://review.openstack.org/#/c/190483/ || Merged
 
|-
 
| /common/section_objectstorage_tenant-specific-image-storage.xml || objectstorage_tenant_specific_image_storage.rst || Brian Moss || https://review.openstack.org/#/c/190483/ || Merged
 
|-
 
|section_compute_config-firewalls.xml || compute_config-firewalls.rst || Joe Robinson || Link to Review || Starting
 
|-
 
|section_compute_rootwrap.xml || compute_rootwrap.rst || Joe Robinson || Link to review || Starting
 
|-
 
|section_compute_configure_migrations.xml || compute_configure_migrations.rst || Joe Robinson || Link to Review || Starting
 
|-
 
|section_compute-system-admin.xml || compute-system-admin.rst || Joe Robinson || Link to review || Starting
 
|-
 
|common/section_compute-configure-console.xml || compute-configure-console.rst || Joe Robinson || Link to review || Starting
 
|-
 
|section_compute-configure-service-groups.xml || compute-configure-service-groups.rst || Joe Robinson || Link to review || Starting
 
|-
 
|section_compute-security.xml || compute-security.rst || Joe Robinson || Link to review || Starting
 
|-
 
|section_compute-recover-nodes.xml || compute-recover-nodes.rst || Joe Robinson || Link to review || Starting
 
|-
 
|section_ts_cinder_config.xml || ts_cinder_config.rst || Joe Robinson || https://review.openstack.org/#/c/192984/1 || Merged
 
|-
 
|blockstorage/section_nfs_backend.xml || blockstorage_nfs_backend.rst || Maria Zlatkova || https://review.openstack.org/#/c/193518 || Merged
 
|-
 
|blockstorage/section_multi_backend.xml || blockstorage_multi_backend.rst || Maria Zlatkova || https://review.openstack.org/#/c/195061 || Merged
 
|-
 
|blockstorage/section_glusterfs_backend.xml || blockstorage_glusterfs_backend.rst || Maria Zlatkova || https://review.openstack.org/#/c/194109/ || Merged
 
|-
 
|blockstorage/section_backup-block-storage-disks.xml || blockstorage_backup_disks.rst || Maria Zlatkova || https://review.openstack.org/#/c/197931/ || Merged
 
|-
 
|blockstorage/section_volume-migration.xml || volume-migration.rst || Maria Zlatkova || Link to review || In progress
 
|-
 
|blockstorage/section_glusterfs_removal.xml || glusterfs_removal.rst || Maria Zlatkova || Link to review || In progress
 
|-
 
|blockstorage/section_volume-backups.xml || volume-backups.rst || Maria Zlatkova || Link to review || In progress
 
|-
 
|blockstorage/section_volume-backups-export-import.xml || volume-backups-export-import.rst || Maria Zlatkova || Link to review || In progress
 
|-
 
|blockstorage/section_ratelimit-volume-copy-bandwidth.xml || ratelimit-volume-copy-bandwidth.rst || Maria Zlatkova || Link to review || In progress
 
|-
 
|blockstorage/section_over_subscription.xml || over_subscription.rst || Maria Zlatkova || Link to review || In progress
 
|-
 
|common/section_support-compute.xml || support-compute.rst || Olga Gusarenko || Link to review || In progress
 
|-
 
|telemetry/section_telemetry-alarms.xml || telemetry-alarms.rst || Olena Logvinova || Link to review || In progress
 
|-
 
|telemetry/section_telemetry-best-practices.xml || telemetry-best-practices.rst || Karen Bradshaw || https://review.openstack.org/194721 || Merged
 
|-
 
|telemetry/section_telemetry-system-architecture.xml || telemetry-system-architecture.rst || Karen Bradshaw || https://review.openstack.org/195063 || Merged
 
|-
 
|telemetry/section_telemetry-troubleshooting-guide.xml || telemetry-troubleshooting-guide.rst || Karen Bradshaw || https://review.openstack.org/195140/ || Merged
 
|-
 
|image/section_glance-nova-image-download.xml || glance-nova-image-download.rst || Alexandra Settle || https://review.openstack.org/#/c/191607/ || Merged
 
|-
 
|image/section_glance-property-protection.xml || glance-property-protection.rst || Alexandra Settle || https://review.openstack.org/#/c/191607/ || Merged
 
|-
 
|compute/section_compute-images-instances.xml || compute-images-instances.rst || Alexandra Settle || https://review.openstack.org/#/c/191607/ || Merged
 
|-
 
| section_telemetry-data-collection.xml || telemetry-data-collection.rst || Brian Moss || https://review.openstack.org/#/c/197390 || Merged
 
|-
 
| section_telemetry-data-retrieval.xml || telemetry-data-retrieval.rst || Brian Moss || https://review.openstack.org/#/c/197390 || Merged
 
|-
 
| section_telemetry-events.xml || telemetry-events.rst || Brian Moss || https://review.openstack.org/#/c/197390 || Merged
 
|-
 
| section_telemetry-measurements.xml || telemetry-measurements.rst || Brian Moss || https://review.openstack.org/#/c/197390 || Merged
 
|-
 
| /common/ch_getstart.xml || /common/get_started_with_openstack.rst || Darren Chan || https://review.openstack.org/#/c/197832/|| In progress
 
|-
 
| /common/section_getstart_compute.xml || /common/get_started_openstack_compute.rst || Darren Chan || https://review.openstack.org/#/c/197832/|| In progress
 
|-
 
| /common/section_storage-concepts.xml || /common/get_started_storage_concepts.rst || Darren Chan || https://review.openstack.org/#/c/197832/ || In progress
 
|-
 
| /common/section_getstart_object-storage.xml || /common/get_started_object_storage.rst || Darren Chan || https://review.openstack.org/#/c/197832/ || In progress
 
|-
 
| /common/section_getstart_block-storage.xml || /common/get_started_block-storage.rst || Darren Chan || https://review.openstack.org/#/c/197832/ || In progress
 
|-
 
| /common/section_getstart_networking.xml || /common/get_started_openstack_networking.rst || Darren Chan || https://review.openstack.org/#/c/197832/ || In progress
 
|-
 
| /common/section_getstart_dashboard.xml || /common/get_started_openstack_dashboard.rst || Darren Chan || https://review.openstack.org/#/c/197832/ || In progress
 
|-
 
| /common/section_keystone-concepts.xml || /common/get_started_openstack_identity.rst || Darren Chan || https://review.openstack.org/#/c/197832/ || In progress
 
|-
 
| /common/section_getstart_image.xml || /common/get_started_openstack_glance.rst || Darren Chan || https://review.openstack.org/#/c/197832/ || In progress
 
|-
 
| /common/section_getstart_telemetry.xml|| /common/get_started_openstack_telemetry.rst || Darren Chan || https://review.openstack.org/#/c/197832/ || In progress
 
|-
 
| /common/section_getstart_orchestration.xml || /common/get_started_openstack_orchestration.rst || Darren Chan || https://review.openstack.org/#/c/197832/ || In progress
 
|-
 
| /common/section_getstart_trove.xml || /common/get_started_openstack_trove.rst || Darren Chan || https://review.openstack.org/#/c/197832/ || In progress
 
|-
 
| /common/section_getstart_sahara.xml || /common/get_started_openstack_sahara.rst || Darren Chan || https://review.openstack.org/#/c/197832/ || In progress
 
|-
 
| /common/section_getstart_conceptual_arch.xml|| /common/get_started_conceptual_architecture.rst || Darren Chan || https://review.openstack.org/#/c/197832/ || In progress
 
|-
 
| /common/section_getstart_logical_arch.xml || /common/get_started_logical_architecture.rst || Darren Chan || https://review.openstack.org/#/c/197832/ || In progress
 
|-
 
| compute/section_compute-configure-ipv6.xml || compute-configure-ipv6.rst || Alexandra Settle ||https://review.openstack.org/#/c/197834/ || In progress
 
|-
 
| compute/section_compute-image-mgt.xml || compute-image-mgt.rst || Alexandra Settle || https://review.openstack.org/#/c/197834/ || In progress
 
|-
 
| compute/section_compute-instance-building-blocks.xml || compute-instance-building-blocks.rst || Alexandra Settle || https://review.openstack.org/#/c/197834/ || In progress
 
|-
 
| compute/section_compute-instance-mgt-tools.xml || compute-instance-mgt-tools.rst || Alexandra Settle || https://review.openstack.org/#/c/197834/ || In progress
 
|-
 
| compute/section_compute-networking-nova.xml || compute-networking-nova.rst || Alexandra Settle || https://review.openstack.org/#/c/197834/ || In progress
 
|-
 
| compute/section_trusted-compute-pools.xml || trusted-compute-pools.rst || Alexandra Settle || https://review.openstack.org/#/c/197834/ || In progress
 
|-
 
| blockstorage/section_consistency_groups.xml || blockstorage-consistency-groups.rst || Brian Moss || https://review.openstack.org/#/c/198585 || On review
 
|-
 
| blockstorage/section_driver_filter_weighing.xml || blockstorage-driver-filter-weighing.rst || Brian Moss || https://review.openstack.org/#/c/198585 || On review
 
|-
 
| blockstorage/section_ts_HTTP_bad_req_in_cinder_vol_log.xml || ts-HTTP-bad-req-in-cinder-vol-log.rst || Brian Moss || Patch URL || In progress
 
|-
 
| blockstorage/section_ts_duplicate_3par_host.xml || ts-duplicate-3par-host.rst || Brian Moss || Patch URL || In progress
 
|-
 
| blockstorage/section_ts_eql_volume_size.xml || ts-eql-volume-size.rst || Brian Moss || Patch URL || In progress
 
|-
 
| blockstorage/section_ts_failed_attach_vol_after_detach.xml || ts-failed-attach-vol-after-detach.rst || Brian Moss || Patch URL || In progress
 
|-
 
| blockstorage/section_ts_failed_attach_vol_no_sysfsutils.xml || ts-failed-attach-vol-no-sysfsutils.rst || Brian Moss || Patch URL || In progress
 
|-
 
| blockstorage/section_ts_failed_connect_vol_FC_SAN.xml || ts-failed-connect-vol-FC-SAN.rst || Brian Moss || Patch URL || In progress
 
|-
 
| blockstorage/section_ts_multipath_warn.xml || RST filename || KATO Tomoyuki || https://review.openstack.org/#/c/197855/ || In progress
 
|-
 
| blockstorage/section_ts_no_emulator_x86_64.xml || RST filename || Darren Chan || Patch URL || Status
 
|-
 
| blockstorage/section_ts_non_existent_host.xml || ts_non_existent_host.rst || Karen Bradshaw || https://review.openstack.org/198333 || In progress
 
|-
 
| blockstorage/section_ts_non_existent_vlun.xml || ts_non_existent_vlun.rst || Karen Bradshaw || https://review.openstack.org/198333 || In progress
 
|-
 
| blockstorage/section_ts_vol_attach_miss_sg_scan.xml || ts_vol_attach_miss_sg_scan.rst || Karen Bradshaw || https://review.openstack.org/198333 || In progress
 
|-
 
| blockstorage/section_volume_number_weighter.xml || RST filename || Darren Chan || Patch URL || Status
 
 
|}
 
|}
  
== Installation Guide Migration ==
+
== Completing conversion to RST ==
 
 
Sign up below for a chapter, then create a patch with RST in doc/install-guide-rst/source for others to review. While the Install Guide Specialty team will be giving the conversion attention, contributions are welcome.
 
 
 
{| class="wikitable"
 
|-
 
! Chapter/Section (old filename) !! Chapter/Section (new filename) !! Name !! Patch URL !! Status
 
|-
 
| Filename || RST converted Filename || Doc Writer || Link to review || Merge Status
 
|-
 
| Filename || RST converted Filename || Doc Writer || Link to review || Merge Status
 
|-
 
| section_basics-database.xml || basics-database.rst || Karen Bradshaw || Link to review || In Progress
 
|-
 
| section_basics-security.xml || basics-security.rst || Karen Bradshaw || Link to review || In Progress
 
|-
 
| section_basics-queue.xml || basics-queue.rst || Karen Bradshaw || Link to review || In Progress
 
|-
 
| ch_overview.xml || overview.rst || Karen Bradshaw || https://review.openstack.org/#/c/197915/ || Merged
 
|-
 
| ch_basic_environment.xml || basic_environment.rst || Karen Bradshaw || https://review.openstack.org/#/c/197915/ || Merged
 
|-
 
| ch_nova.xml || nova.rst || KATO Tomoyuki || https://review.openstack.org/#/c/197793/ || Merged
 
|-
 
| section_nova-controller-install.xml || nova-controller-install.rst || KATO Tomoyuki || https://review.openstack.org/#/c/197793/ || Merged
 
|-
 
| section_nova-compute-install.xml || nova-compute-install.rst || KATO Tomoyuki || Link to review || In Progress
 
|-
 
| section_nova-verify.xml || nova-verify.rst || KATO Tomoyuki || Link to review || In Progress
 
|-
 
| ch_networking.xml || networking.rst || Robb Romans || Link to review || In Progress
 
|-
 
| section_neutron-concepts.xml || neutron_concepts.rst || Robb Romans || Link to review || In Progress
 
|-
 
| section_neutron-controller-node.xml || neutron_controller_node.rst || Robb Romans || Link to review || In Progress
 
|-
 
| section_neutron-network-node.xml || neutron_network_node.rst || Robb Romans || Link to review || In Progress
 
|-
 
| section_neutron-compute-node.xml || neutron_compute_node.rst || Robb Romans || Link to review || In Progress
 
|-
 
| section_neutron-initial-networks.xml || neutron_initial_networks.rst || Robb Romans || Link to review || In Progress
 
|-
 
| section_nova-networking-controller-node.xml || nova_networking_controller_node.rst || Robb Romans || Link to review || In Progress
 
|-
 
| section_nova-networking-compute-node.xml || nova_networking_compute_node.rst || Robb Romans || Link to review || In Progress
 
|-
 
| section_nova-networking-initial-network.xml || nova_networking_initial_network.rst || Robb Romans || Link to review || In Progress
 
|-
 
| ch_horizon.xml || horizon.rst || KATO Tomoyuki || https://review.openstack.org/#/c/197133/ || Merged
 
|-
 
| section_dashboard-install.xml || dashboard-install.rst || KATO Tomoyuki || https://review.openstack.org/#/c/198017/ || Merged
 
|-
 
| section_dashboard-verify.xml || dashboard-verify.rst || KATO Tomoyuki || https://review.openstack.org/#/c/198017/ || Merged
 
|-
 
| ch_swift.xml || swift.rst || Christian Berendt || https://review.openstack.org/#/c/195996/ || In Progress
 
|-
 
| section_swift-controller-node.xml || swift_controller_node.rst || Christian Berendt || https://review.openstack.org/#/c/195996/ || In Progress
 
|-
 
| section_swift-finalize-installation.xml || swift_finalize_installation.rst || Christian Berendt || https://review.openstack.org/#/c/195996/ || In Progress
 
|-
 
| section_swift-initial-rings.xml || swift_initial_rings.rst || Christian Berendt || https://review.openstack.org/#/c/195996/ || In Progress
 
|-
 
| section_swift-storage-node.xml || swift_storage_node.rst || Christian Berendt || https://review.openstack.org/#/c/195996/ || In Progress
 
|-
 
| section_swift-verify.xml || swift_verify.rst || Christian Berendt || https://review.openstack.org/#/c/195996/ || In Progress
 
|}
 
 
 
== Doc Migration Plan ==
 
 
 
In Kilo we are migrating the End User Guide and the Admin User Guide. Refer to the [http://specs.openstack.org/openstack/docs-specs/specs/kilo/migrate-to-new-web-design.html detailed specification] for the 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:
 
 
 
<pre>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</pre>
 
 
 
Clean up where the fixmefixmefixme 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.
+
Once we have reviewed the draft guide and think it's ready to publish, we need to do the following steps:
  
Remove "programlisting" "screen" and "literallayout" from .. code:: lines.
+
# Create a patch with the following steps (for example, see https://review.openstack.org/#/c/248577/ or https://review.openstack.org/211766) 
 +
## Delete the old guide, here security-guide
 +
## Move the RST guide to the location of new guide (security-guide-rst -> security-guide).
 +
## Update tools/build-all-rst.sh for the change
 +
## Delete the entry from doc/pom.xml
 +
## Update RELEASENOTES.rst
 +
## If the repository has no further DocBook guides in it, update tox.ini
 +
## Update doc-tools-check-languages.conf
 +
## Rename localization files to new directory name
 +
## If there is a ".tx/config" file, update it (remove RST guide and update paths)
 +
# If the repository has no further DocBook guides in it:
 +
#* Remove jobs from Jenkins. For example: https://review.openstack.org/211843
 +
#* Cleanup tox.ini. For example: https://review.openstack.org/212127
 +
#* Remove tools/generatepot. For example: https://review.openstack.org/212129
 +
# Update .gitignore. For example: https://review.openstack.org/212685
 +
# If the repository is not the openstack-manuals repo, stop syncing of XML files: https://review.openstack.org/211842 and remove the copied files once that patch is merged: https://review.openstack.org/211904
 +
# Fix links on docs.openstack.org and in other guides: https://review.openstack.org/212044
 +
#* Create redirects from content directory to top-level index.html file
 +
#* Update all links so that they go to new guide (security-guide, not security-guide/content)
 +
#* Remove links to PDF of guide
 +
# Sync translations from old guide with new guide (needs to be done in transifex by Andreas)
 +
# Tell i18n team that conversion is finished and which resource is active.
 +
# Remove old guide and draft RST guides from docs.openstack.org (needs docs.openstack.org admin access)
 +
# Regenerate sitemap.xml after all changes are in: https://review.openstack.org/212689 and blacklist the change: https://review.openstack.org/212690
  
== Publishing User Guides ==
 
  
Proposed next steps for publishing the user guides on the 9th of April:
 
# Fix openstackdocstheme "log a bug" and release new openstackdocstheme (annegentle, done) (independent of other steps but should be done before release)
 
# Review that all content exists (annegentle, karenb, done)
 
# Rename playground-user-guide directory to user-guides  (ajaeger, done)
 
# Rename on transifex as well (ajaeger, done)
 
# Split files in doc/user-guides/source into (ajaeger, done):
 
#* doc/user-guides/source/common: files shared by both guides
 
#* doc/user-guides/source/adminuser: files only for Admin User Guide
 
#* doc/user-guides/source/enduser: files only for End User Guide
 
# Publish content on docs.openstack.org for review (ajaeger, done):
 
#* End User Guide: docs.openstack.org/draft/user-guide/
 
#* Admin User Guide: docs.openstack.org/draft/user-guide-admin/
 
# Review contents and fix (karenb, starting with admin guide, can continue after publication)
 
# On the 17th of April, publish converted RST User Guides to:
 
#* End User Guide: docs.openstack.org/user-guide/
 
#* Admin User Guide: docs.openstack.org/user-guide-admin/
 
# Steps for this:
 
#* Publishing new content, 6:00 UTC or later, ajaeger will approve and do fixes as needed:
 
#** Remove entries from .tx/config for guides (ajaeger, done)
 
#** Remove doc/user-guide, doc/user-guide-admin, doc/hot-guide/ directories (ajaeger, merged): https://review.openstack.org/171683
 
#** publish new User Guides to proper place (ajaeger): part of patch above
 
#** Update entries to index.html pages pointing to new content (annegentle, merged): https://review.openstack.org/#/c/174380/
 
#* Removal of old content, 12:00 UTC or later, annegentle will approve and do fixes as needed:
 
#** Update sitemap.xml (annegentle) https://review.openstack.org/#/c/174837/
 
#** Add redirects for moved pages removing extra /content/ directory (annegentle) https://review.openstack.org/#/c/174835/
 
#** Remove old pages from /content/ directory for both user-guide and user-guide-admin on FTP server (annegentle) Will wait for redirects to be in place.
 
# Search for old links. Go through our repos for  (just search for "user-guide/content" and "user-guide-admin/content") and replace links with new location.
 
Please review and enhance so that we don't miss anything!
 
 
----
 
----
 
[[Category:Documentation]]
 
[[Category:Documentation]]

Latest revision as of 08:36, 2 August 2016

Doc Migration from DocBook to RST Overview

Previously, we migrated the <service>-api repos from DocBook to RST. These were API reference documents that 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.

Migration Conventions

Follow the RST markup conventions in the OpenStack Documentation Contributor Guide .

Headings

First title in an RST file, use equals signs above and below. Second title, use tilde. Third title, use a series of dashes. Try not to need a Heading 4 if you can help it by rewriting or reorganizing.



========
Heading 1
========

Heading 2
~~~~~~~~~

Heading 3
---------

File names

As a rule, we want to keep the xml:id identical so that the output HTML files do not need redirection. However, we also at the same time want to get rid of ch_ and section_ nomenclatures while going to a page-based, topical approach. So, first use the XML:ID, and if the XML:ID has ch_ or section_ in it, remove the prefix.

Cross references

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.

Also, while intersphinx is an enabled extension for many of the contributor developer docs, we don't have an intersphinx requirement yet for the end user guide or admin user guide. We'll investigate that as we add more guides.

Figures and images

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

Notes and admonitions

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

Line numbers in code blocks

If your file has lots of code blocks, be sure to set up line numbering for the entire file. Each code-block must have :linenos: after the .. code-block:: directive, the code itself must be indented at the same level as the :lineos: line, and you must have at the start of the file this directive:

.. highlight: python
   :linenothreshold: 5

so that any code-blocks longer than five lines long will have line numbers.

Migration Issues

List of bugs or missing features for the Sphinx template, openstackdocstheme: https://bugs.launchpad.net/openstack-manuals/+bugs?field.tag=openstackdocstheme

Can you have line breaks in something with inline semantic markup like :guilabel: at the end of the line? For example:


#. Select the volume to add to an instance and click :guilabel:`Edit Attachments`.

That line is longer than 79 characters, so Attachments`. must be on the second line, but when you do that, the HTML output is incorrect.

Since RST documents impose a 79 character limit when building files in .rst format. When tables exceed that limit, a list table role can help create content in a new table without exceeding the character limit. The issue is when a table is generated by an OpenStack service, and returned as a result of a command. These tables are constructed with +, -, and | characters. The table created by a list table role has solid lines forming rows, columns, and cells. The content is similar, however users might be surprised by a table with solid lines rather than a table built with +, -, and | characters.

Large scale content inside tables.

When building tables with a list table role, some items that appear inside the table cells might exceed the 79 character limit. Is there a solution to recreating this large scale content in a table such that it does not affect the character limit?

The :orphan: role and references.

Files with an :orphan: role at the top of the file, not included in the toc tree, will not link to another file when the :ref: role is used to link to the file from a different file. Is there a solution to this linking issue?

Pandoc conversion problems.

When converting files with Pandoc, some entries in the .xml file will not convert accurately. Procedure titles and sub section titles will not parse correctly, and will be deleted from the converted document. Pandoc also removes procedure numbering. Currently, the solution is to compare the complete .rst file to the built .xml version, and check the headings, subheadings, and procedure numbers to make sure they are correct, and line up with original. This is an issue that could also be discussed.

  • Contact details for RST issues that we can't solve:
    • Author: David Goodger
    • Contact: docutils-develop@lists.sourceforge.net

Migration How To

Note: If you don't want to use tox, install these prereqs locally: pip install sphinx; pip install openstackdocstheme and then switch to the directory containing a conf.py and run sphinx-build /path/to/source/ path/to/build/ to get html output by default.

Because Sphinx builds have dependent requirements it is best to work with in a virtual environment. Fortunately the openstack-manuals project already has tox set up so that you can create a virtualenv that contains the required dependencies. To use it, do this on a Mac or Ubuntu machine with Python and pip already installed:

  1. Clone the openstack-manuals repository.
  2. Change directories into openstack-manuals.
  3. Run this:
    tox -e py27
  4. When you get a congratulations message, run this:

Mac/Ubuntu:

source .tox/py27/bin/activate

Windows:

 source .tox/py27/Scripts/activate

Your prompt should now have (py27) as a preface.

Now you have all the pre-requisites installed and can run additional tox commands. To see the list of commands, view or edit tox.ini in the openstack-manuals directory. To build the RST docs, run:

tox -e docs

This will run sphinx-build doc/playground-user-guide/source/ doc/playground-user-guide/build/html.

When the build is finished, you can open doc/playground-user-guide/build/html/index.html to view the resulting output.

Migration Using Oxygen

  1. Open DocBook book file in Oxygen.
  2. Choose Document > Transformation > Configure Transformation Scenario(s).
  3. Select DocBook XHTML - Chunk.
  4. Click Apply associated (1).
  5. 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<pre><nowiki>
    # 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
  6. Clean up where the fixmefixmefixme is output, it indicates where a cross-reference cannot exist any longer.
  7. Clean up tables where the pandoc conversion just outputs paragraphs.
  8. Remove numbering from Example titles and Table titles.
  9. 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.
  10. Remove "programlisting" "screen" and "literallayout" from .. code:: lines.
  11. When commiting conversion patches, include the related blueprint in your commit message. For example:
    Convert ch_compute_focus.xml to RST
    Implements: blueprint archguide-mitaka-rst

Migration Using a Text Editor

  1. Install pandoc.
  2. Update your openstack-manuals master branch, and create a branch.
  3. Run the pandoc command to convert the .xml file to .rst. For example:
    pandoc -f docbook -t rst -s ch_compute_focus.xml -o compute-focus.rst
  4. Move converted files to the <guide>/source folder.
  5. Rename converted RST 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.
  6. Pandoc has its quirks, so check all the content has been migrated from the source file.
  7. Use a text editor to complete the following tasks:
    1. Clean up tables where the pandoc conversion just outputs paragraphs.
    2. Remove numbering from Example titles and Table titles.
    3. Remove "programlisting" "screen" and "literallayout" from .. code:: lines.
    4. Check the converted RST file follow conventions described in the OpenStack Documentation Contributor Guide
  8. Build the guide locally, to check for errors:
    tox -e docs
  9. Commit your changes, including the related blueprint in your commit message. For example:
    Convert ch_compute_focus.xml to RST
    Implements: blueprint archguide-mitaka-rst

Doc Migration Plan

For the Mitaka release, we migrated the Configuration Reference Guide and the Architecture Design Guide. Refer to the detailed specification for details.

API Reference Plan

See http://docs.openstack.org/contributor-guide/api-guides.html for explanation of the process. Anne has already preprocessed the files, so the other migration steps on this wiki page are not needed at all.

Sign up below for a service, then download the files from this patch: https://review.openstack.org/#/c/311596/. These will require a lot of cleanup manually but gets them as far as the tools can get them. Also, setup a job to publish data like https://review.openstack.org/312184.

Service name Service version Project Name Patch URL Status
Compute v2.1 nova Sean Dague https://review.openstack.org/#/q/status:merged+project:openstack/nova+branch:master+topic:bp/api-ref-in-rst In progress
Identity v2.0 keystone Samuel de Medeiros Queiroz https://review.openstack.org/#/q/project:openstack/keystone+branch:master+topic:migrate-identity-api-ref In progress
Identity v3 (and extensions) keystone Samuel de Medeiros Queiroz https://review.openstack.org/#/q/project:openstack/keystone+branch:master+topic:migrate-identity-api-ref In progress
Bare metal v1 ironic Jim Rollenhagen https://review.openstack.org/#/c/312181/ and https://review.openstack.org/312184 In progress
Block Storage v1 cinder Sheel Rana Insaan https://review.openstack.org/#/c/312113 In progress
Block Storage v2 cinder Sheel Rana Insaan https://review.openstack.org/#/c/312113 In progress
Clustering v1 senlin
Data Processing v1.1 sahara Note: has these REST API docs http://docs.openstack.org/developer/sahara/restapi/rest_api_v1.0.html
Database v1.0 trove Laurel Michaels https://review.openstack.org/#/c/316381 Needs review, can't build locally
Image v1 glance rosmaita https://review.openstack.org/#/c/312259/ and https://review.openstack.org/#/c/315191/ merged
Image v2 glance rosmaita https://review.openstack.org/#/c/332950/ merged
Tasks v2 glance rosmaita https://review.openstack.org/#/c/333029/ merged
Metadefs v2 glance rosmaita https://review.openstack.org/#/c/333031/ merged
Networking v2.0 (and extensions) neutron HenryG, amotoki https://review.openstack.org/#/c/314819/ In progress
Object Storage v1 swift Anne Gentle https://review.openstack.org/312315 In review
Orchestration v1 heat Jay Dobies (jdob) https://review.openstack.org/#/c/312712/ and https://review.openstack.org/312726 Complete :)
Shared File Systems v1 manila Daniel Gonzalez https://review.openstack.org/#/c/313874 and https://review.openstack.org/#/c/313875 Merged
Shared File Systems v2 manila Daniel Gonzalez https://review.openstack.org/#/c/313874 and https://review.openstack.org/#/c/313875 Merged
Telemetry v2 ceilometer Note: has these REST API docs http://docs.openstack.org/developer/ceilometer/webapi/v2.html

Operations Guide

Sign up below for a chapter, then create a patch with RST in doc/ops-guide/source for others to review. Contributions are welcome. Please add "Implements: blueprint ops-guide-rst" in the commit message.

Please make sure this book follows O'Reilly conventions.

Chapter/Section (old filename) Chapter/Section (new filename) Name Patch URL Status
bk_ops_guide.xml
preface_ops.xml preface_ops.rst venkatamahesh https://review.openstack.org/#/c/292071 Merged
part_architecture.xml part_architecture.rst venkatamahesh https://review.openstack.org/#/c/292064 Merged
part_operations.xml operations.rst KATO Tomoyuki https://review.openstack.org/#/c/291987/ Merged
ch_arch_cloud_controller.xml ch_arch_cloud_controller.rst venkatamahesh https://review.openstack.org/#/c/292061 Merged
ch_arch_compute_nodes.xml ch_arch_compute_nodes.rst venkatamahesh https://review.openstack.org/#/c/292059 Merged
ch_arch_examples.xml ch_arch_examples.rst venkatamahesh https://review.openstack.org/#/c/292052 Merged
section_arch_example-neutron.xml section_arch_example-neutron.rst venkatamahesh https://review.openstack.org/#/c/291965 Merged
section_arch_example-nova.xml section_arch_example-nova.rst venkatamahesh https://review.openstack.org/#/c/291783 Merged
ch_arch_network_design.xml ch_arch_network_design.rst venkatamahesh https://review.openstack.org/#/c/291974 Merged
ch_arch_provision.xml ch_arch_provision.rst venkatamahesh https://review.openstack.org/#/c/291976 Merged
ch_arch_scaling.xml ch_arch_scaling.rst venkatamahesh https://review.openstack.org/#/c/291978 Merged
ch_arch_storage.xml ch_arch_storage.rst venkatamahesh https://review.openstack.org/#/c/292007 Merged
ch_ops_advanced_configuration.xml ch_ops_advanced_configuration.rst venkatamahesh https://review.openstack.org/#/c/292008 Merged
ch_ops_backup_recovery.xml ch_ops_backup_recovery.rst venkatamahesh https://review.openstack.org/#/c/292011 Merged
ch_ops_customize.xml ch_ops_customize.rst venkatamahesh https://review.openstack.org/#/c/292013 Merged
ch_ops_lay_of_land.xml lay_of_the_land.rst KATO Tomoyuki https://review.openstack.org/#/c/291996/ Merged
ch_ops_log_monitor.xml ch_ops_log_monitor.rst venkatamahesh https://review.openstack.org/#/c/292015 Merged
ch_ops_maintenance.xml ch_ops_maintenance.rst venkatamahesh https://review.openstack.org/#/c/292022 Merged
ch_ops_network_troubleshooting.xml ch_ops_network_troubleshooting.rst venkatamahesh https://review.openstack.org/#/c/292027 Merged
ch_ops_projects_users.xml projects_users.rst KATO Tomoyuki https://review.openstack.org/#/c/292002/ Merged
ch_ops_resources.xml ch_ops_resources.rst venkatamahesh https://review.openstack.org/#/c/292033 Merged
ch_ops_upgrades.xml ch_ops_upgrades.rst venkatamahesh https://review.openstack.org/#/c/292035 Merged
ch_ops_upstream.xml ch_ops_upstream.rst venkatamahesh https://review.openstack.org/#/c/292036 Merged
ch_ops_user_facing.xml ch_ops_user_facing.rst venkatamahesh https://review.openstack.org/#/c/292050 Merged

Completing conversion to RST

Once we have reviewed the draft guide and think it's ready to publish, we need to do the following steps:

  1. Create a patch with the following steps (for example, see https://review.openstack.org/#/c/248577/ or https://review.openstack.org/211766)
    1. Delete the old guide, here security-guide
    2. Move the RST guide to the location of new guide (security-guide-rst -> security-guide).
    3. Update tools/build-all-rst.sh for the change
    4. Delete the entry from doc/pom.xml
    5. Update RELEASENOTES.rst
    6. If the repository has no further DocBook guides in it, update tox.ini
    7. Update doc-tools-check-languages.conf
    8. Rename localization files to new directory name
    9. If there is a ".tx/config" file, update it (remove RST guide and update paths)
  2. If the repository has no further DocBook guides in it:
  3. Update .gitignore. For example: https://review.openstack.org/212685
  4. If the repository is not the openstack-manuals repo, stop syncing of XML files: https://review.openstack.org/211842 and remove the copied files once that patch is merged: https://review.openstack.org/211904
  5. Fix links on docs.openstack.org and in other guides: https://review.openstack.org/212044
    • Create redirects from content directory to top-level index.html file
    • Update all links so that they go to new guide (security-guide, not security-guide/content)
    • Remove links to PDF of guide
  6. Sync translations from old guide with new guide (needs to be done in transifex by Andreas)
  7. Tell i18n team that conversion is finished and which resource is active.
  8. Remove old guide and draft RST guides from docs.openstack.org (needs docs.openstack.org admin access)
  9. Regenerate sitemap.xml after all changes are in: https://review.openstack.org/212689 and blacklist the change: https://review.openstack.org/212690