Jump to: navigation, search

Difference between revisions of "Documentation/Migrate"

(End User Guide Migration)
(Admin User Guide Migration)
Line 122: Line 122:
  
 
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.
 
== 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.
 
 
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"
 
|-
 
! Chapter/Section (old filename) !! Chapter/Section (new filename) !! 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
 
|-
 
| section_cli_nova_host_servers_migrate.xml || xmlid.rst || Olga Gusarenko || Not used currently or find a proper place for it || Deferred
 
|-
 
| section_cli_nova_manage_flavors || cli_manage_flavors.rst || Olga Gusarenko || https://review.openstack.org/#/c/168797 || Merged
 
|-
 
| section_cli_nova_manage_projects_security || nova_cli_manage_projects_security.rst || Anne Gentle || https://review.openstack.org/#/c/156877 || Merged
 
|-
 
| section_cli_nova_migrate.xml || cli_nova_migrate.rst || Maria Zlatkova || https://review.openstack.org/#/c/167178 || Merged
 
|-
 
| section_cli_nova_services.xml || cli_nova_manage_services.rst || Olga Gusarenko || https://review.openstack.org/#/c/166786 || Merged
 
|-
 
| section_cli_nova_specify_host.xml || cli_nova_specify_host.rst || Olga Gusarenko || https://review.openstack.org/#/c/168869 || Merged
 
|-
 
| section_dashboard_admin_manage_flavors.xml || dashboard_manage_flavors.rst || Olena Logvinova || https://review.openstack.org/#/c/167154 || Merged
 
|-
 
| section_dashboard_admin_manage_host_aggregates.xml || dashboard_manage_host_aggregates.rst || Anne Gentle || https://review.openstack.org/163198 || Merged
 
|-
 
| section_dashboard_admin_manage_images.xml || dashboard_manage_images.rst || Olena Logvinova || https://review.openstack.org/#/c/167950/2 || Merged
 
|-
 
| section_dashboard_admin_manage_resources.xml || dashboard_manage_resources.rst || Karen Bradshaw || https://review.openstack.org/#/c/165583/ || Merged
 
|-
 
| section_dashboard_admin_manage_roles.xml || dashboard_admin_manage_roles.rst || Olena Logvinova || https://review.openstack.org/166241 || Merged
 
|-
 
| section_dashboard_admin_manage_services.xml || dashboard_manage_services.rst || Karen Bradshaw || https://review.openstack.org/#/c/165486/ || Merged
 
|-
 
| section_dashboard_admin_manage_stacks.xml || dashboard_manage_stacks.rst || Olena Logvinova || https://review.openstack.org/#/c/168303 || Merged
 
|-
 
| section_dashboard_admin_set_quotas.xml || dashboard_set_quotas.rst || Karen Bradshaw || https://review.openstack.org/#/c/166306 || Merged
 
|-
 
| section_dashboard_admin_view_cloud_resources.xml || dashboard_view_cloud_resources.rst || Karen Bradshaw || https://review.openstack.org/#/c/165499/ || Merged
 
|-
 
| section_cli_keystone_manage_projects_users_roles.xml || admin_cli_manage_projects_users.rst || Anne Gentle || https://review.openstack.org/#/c/156877/ || Merged
 
|-
 
| section_cli_keystone_manage_projects_users_roles.xml || nova_cli_manage_projects_security.rst || Anne Gentle || https://review.openstack.org/#/c/156877/ || Merged
 
|-
 
| section_dashboard_admin_manage_instances.xml || dashboard_manage_instances.rst || Anne Gentle || https://review.openstack.org/163082 || Merged
 
|-
 
| 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 ==
 
== Cloud Admin Guide Migration ==

Revision as of 18:05, 12 August 2015

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.

Migration Conventions

Follow the existing existing markup conventions for RST.

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

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

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:


#. 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.

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:

Clone the openstack-manuals repo.

Change directories into openstack-manuals.

Run this:

tox -e py27

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.

Cloud Admin Guide Migration

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:

  Convert chap_database.xml to RST

  Implements: blueprint reorganise-user-guides
  Change-Id: I12343297fsaf782fd8802478236fds2067eaq127890
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
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 https://review.openstack.org/#/c/199369/ Merged
/network/section_networking_adv_features.xml section_networking_adv_features.rst Alexandra Settle https://review.openstack.org/#/c/201793/ Merged
/network/section_networking-adv-config.xml networking-adv-config.rst Alexandra Settle https://review.openstack.org/#/c/199369/ Merged
/network/section_networking_adv_operational_features.xml networking_adv_operational_features.rst Alexandra Settle https://review.openstack.org/#/c/199369/ Merged
/network/section_networking_arch.xml networking_arch.rst Alexandra Settle https://review.openstack.org/#/c/199369/ Merged
/network/section_networking_auth.xml networking_auth.rst Alexandra Settle https://review.openstack.org/#/c/199369/ Merged
/network/section_networking_config-agents.xml networking_config-agents.rst Alexandra Settle https://review.openstack.org/#/c/199870/ Merged
/network/section_networking_config-plugins.xml networking_config-plugins.rst Alexandra Settle https://review.openstack.org/#/c/199369/ Merged
/network/section_networking_introduction.xml networking_introduction.rst Alexandra Settle https://review.openstack.org/#/c/199870/ Merged
/network/section_networking-config-identity.xml networking-config-identity.rst Alexandra Settle https://review.openstack.org/#/c/201793/ Merged
/network/section_networking-multi-dhcp-agents.xml networking-multi-dhcp-agents.rst Alexandra Settle https://review.openstack.org/#/c/199870/ Merged
/network/section_networking-use.xml networking-use.rst Alexandra Settle https://review.openstack.org/#/c/199369/ Merged
/common/section_identity-troubleshooting.xml identity_management.rst (not common content) Darren Chan https://review.openstack.org/#/c/189566/ Merged
/common/section_keystone-concepts-user-management.xml identity_management.rst Darren Chan https://review.openstack.org/#/c/189566/ Merged
/common/section_keystone-concepts-service-management.xml identity_management.rst Darren Chan https://review.openstack.org/#/c/189566/ Merged
/common/section_keystone-concepts-group-management.xml identity_management.rst Darren Chan https://review.openstack.org/#/c/189566/ Merged
/common/section_keystone_certificates-for-pki.xml keystone_certificates_for_pki.rst Darren Chan https://review.openstack.org/#/c/193958/ Merged
/common/section_keystone-ssl-config.xml keystone_configure_with_SSL.rst Darren Chan https://review.openstack.org/#/c/193958/ Merged
/common/section_keystone-external-auth.xml keystone_external_authentication.rst Darren Chan https://review.openstack.org/#/c/193958/ Merged
/common/section_keystone_config_ldap.xml keystone_integrate_with_LDAP.rst Darren Chan https://review.openstack.org/#/c/194520/ Merged
identity/section_keystone-token-binding.xml keystone_token-binding.rst Darren Chan https://review.openstack.org/#/c/194520/ Merged
identity/section_keystone-trusts.xml keystone_use_trusts.rst Darren Chan https://review.openstack.org/#/c/194520/ Merged
identity/section_caching-layer.xml keystone_caching_layer.rst Darren Chan https://review.openstack.org/#/c/194520/ Merged
common/section_keystone_config_ldap-identity.xml keystone_integrate_identity_backend_ldap.rst Darren Chan https://review.openstack.org/#/c/194520/ Merged
identity/section_keystone_config_ldap-assignments.xml keystone_integrate_assignment_backend_ldap.rst Darren Chan https://review.openstack.org/#/c/194520/ Merged
identity/section_keystone_config_ldap-hardening.xml keystone_secure_identity_to_ldap_backend.rst Darren Chan https://review.openstack.org/#/c/194520/ Merged
section_orchestration-auth-model.xml orchestration-auth-model.rst Olena Logvinova https://review.openstack.org/#/c/192575 Merged
section_orchestration-stack-domain-users.xml orchestration-stack-domain-users.rst Olena Logvinova https://review.openstack.org/#/c/195668/ Merged
ch_objectstorage.xml objectstorage.rst Karen Bradshaw https://review.openstack.org/#/c/189806/ 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 https://review.openstack.org/#/c/197882/ Merged
section_compute_rootwrap.xml compute_rootwrap.rst Joe Robinson https://review.openstack.org/#/c/197882/ Merged
section_compute_configure_migrations.xml compute_configure_migrations.rst Joe Robinson https://review.openstack.org/#/c/197882/ Merged
section_compute-system-admin.xml compute-system-admin.rst Joe Robinson https://review.openstack.org/#/c/197882/ Merged
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 https://review.openstack.org/#/c/197882/ Merged
section_compute-security.xml compute-security.rst Joe Robinson https://review.openstack.org/#/c/197882/ Merged
section_compute-recover-nodes.xml compute-recover-nodes.rst Joe Robinson https://review.openstack.org/#/c/197882/ Merged
section_ts_cinder_config.xml ts_cinder_config.rst Joe Robinson https://review.openstack.org/#/c/192984 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_glusterfs_removal.xml blockstorage_glusterfs_removal.rst zhu.rong https://review.openstack.org/#/c/199857/ Merged
blockstorage/section_volume-migration.xml blockstorage_volume_migration.rst zhangguoqing https://review.openstack.org/#/c/199912/ Merged
blockstorage/section_volume-backups.xml blockstorage_volume_backups.rst zhangguoqing https://review.openstack.org/#/c/199860/ Merged
blockstorage/section_volume-backups-export-import.xml blockstorage_volume_backups_export_import.rst zhangguoqing https://review.openstack.org/#/c/199869/ Merged
blockstorage/section_ratelimit-volume-copy-bandwidth.xml blockstorage_ratelimit_volume_copy_bandwidth.rst zhangguoqing https://review.openstack.org/#/c/199512/ Merged
blockstorage/section_over_subscription.xml blockstorage_over_subscription.rst zhangguoqing https://review.openstack.org/#/c/199842/ Merged
common/section_support-compute.xml support-compute.rst Olga Gusarenko https://review.openstack.org/#/c/196047/ Merged
telemetry/section_telemetry-alarms.xml telemetry-alarms.rst Olena Logvinova https://review.openstack.org/#/c/204570 Merged
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/ Merged
/common/section_getstart_compute.xml /common/get_started_openstack_compute.rst Darren Chan https://review.openstack.org/#/c/197832/ Merged
/common/section_storage-concepts.xml /common/get_started_storage_concepts.rst Darren Chan https://review.openstack.org/#/c/197832/ Merged
/common/section_getstart_object-storage.xml /common/get_started_object_storage.rst Darren Chan https://review.openstack.org/#/c/197832/ Merged
/common/section_getstart_block-storage.xml /common/get_started_block-storage.rst Darren Chan https://review.openstack.org/#/c/197832/ Merged
/common/section_getstart_networking.xml /common/get_started_openstack_networking.rst Darren Chan https://review.openstack.org/#/c/197832/ Merged
/common/section_getstart_dashboard.xml /common/get_started_openstack_dashboard.rst Darren Chan https://review.openstack.org/#/c/197832/ Merged
/common/section_keystone-concepts.xml /common/get_started_openstack_identity.rst Darren Chan https://review.openstack.org/#/c/197832/ Merged
/common/section_getstart_image.xml /common/get_started_openstack_glance.rst Darren Chan https://review.openstack.org/#/c/197832/ Merged
/common/section_getstart_telemetry.xml /common/get_started_openstack_telemetry.rst Darren Chan https://review.openstack.org/#/c/197832/ Merged
/common/section_getstart_orchestration.xml /common/get_started_openstack_orchestration.rst Darren Chan https://review.openstack.org/#/c/197832/ Merged
/common/section_getstart_trove.xml /common/get_started_openstack_trove.rst Darren Chan https://review.openstack.org/#/c/197832/ Merged
/common/section_getstart_sahara.xml /common/get_started_openstack_sahara.rst Darren Chan https://review.openstack.org/#/c/197832/ Merged
/common/section_getstart_conceptual_arch.xml /common/get_started_conceptual_architecture.rst Darren Chan https://review.openstack.org/#/c/197832/ Merged
/common/section_getstart_logical_arch.xml /common/get_started_logical_architecture.rst Darren Chan https://review.openstack.org/#/c/197832/ Merged
compute/section_compute-configure-ipv6.xml compute-configure-ipv6.rst Alexandra Settle https://review.openstack.org/#/c/197834/ Merged
compute/section_compute-image-mgt.xml compute-image-mgt.rst Alexandra Settle https://review.openstack.org/#/c/197834/ Merged
compute/section_compute-instance-building-blocks.xml compute-instance-building-blocks.rst Alexandra Settle https://review.openstack.org/#/c/197834/ Merged
compute/section_compute-instance-mgt-tools.xml compute-instance-mgt-tools.rst Alexandra Settle https://review.openstack.org/#/c/197834/ Merged
compute/section_compute-networking-nova.xml compute-networking-nova.rst Alexandra Settle https://review.openstack.org/#/c/197834/ Merged
compute/section_trusted-compute-pools.xml trusted-compute-pools.rst Alexandra Settle https://review.openstack.org/#/c/197834/ Merged
blockstorage/section_consistency_groups.xml blockstorage-consistency-groups.rst Brian Moss https://review.openstack.org/#/c/198585 Merged
blockstorage/section_driver_filter_weighing.xml blockstorage-driver-filter-weighing.rst Brian Moss https://review.openstack.org/#/c/198585 Merged
blockstorage/section_ts_HTTP_bad_req_in_cinder_vol_log.xml ts-HTTP-bad-req-in-cinder-vol-log.rst Brian Moss https://review.openstack.org/#/c/199351 Merged
blockstorage/section_ts_duplicate_3par_host.xml ts-duplicate-3par-host.rst Brian Moss https://review.openstack.org/#/c/199351 Merged
blockstorage/section_ts_eql_volume_size.xml ts-eql-volume-size.rst Brian Moss https://review.openstack.org/#/c/199351 Merged
blockstorage/section_ts_failed_attach_vol_after_detach.xml ts-failed-attach-vol-after-detach.rst Brian Moss https://review.openstack.org/#/c/199351 Merged
blockstorage/section_ts_failed_attach_vol_no_sysfsutils.xml ts-failed-attach-vol-no-sysfsutils.rst Brian Moss https://review.openstack.org/#/c/199351 Merged
blockstorage/section_ts_failed_connect_vol_FC_SAN.xml ts-failed-connect-vol-FC-SAN.rst Brian Moss https://review.openstack.org/#/c/199351 Merged
blockstorage/section_ts_multipath_warn.xml ts_multipath_warn.rst KATO Tomoyuki https://review.openstack.org/#/c/197855/ Merged
blockstorage/section_ts_no_emulator_x86_64.xml ts_no_emulator_x86_64.rst Darren Chan https://review.openstack.org/#/c/198982/ Merged
blockstorage/section_ts_non_existent_host.xml ts_non_existent_host.rst Karen Bradshaw https://review.openstack.org/198333 Merged
blockstorage/section_ts_non_existent_vlun.xml ts_non_existent_vlun.rst Karen Bradshaw https://review.openstack.org/198333 Merged
blockstorage/section_ts_vol_attach_miss_sg_scan.xml ts_vol_attach_miss_sg_scan.rst Karen Bradshaw https://review.openstack.org/198333 Merged
blockstorage/section_volume_number_weighter.xml blockstorage_volume_number_weighter.rst zhu.rong https://review.openstack.org/#/c/199843/ Merged
common/section_cli_nova_usage_statistics.xml nova_usage_statistics.rst zhu.rong https://review.openstack.org/#/c/205800/ Status
common/section_compute-configure-console.xml compute-system-admin.rst Darren Chan https://review.openstack.org/#/c/205375/ Merged
common/section_compute-configure-vnc.xml compute-system-admin.rst Darren Chan https://review.openstack.org/#/c/205375/ Merged
common/section_compute-configure-spice.xml compute-system-admin.rst Darren Chan https://review.openstack.org/#/c/205375/ Merged
common/section_objectstorage-troubleshoot.xml objectstorage-troubleshoot.rst Brian Moss https://review.openstack.org/#/c/210995/ In Progress
common/tables/nova-livemigration.xml (automatically generated) nova-livemigration.rst Name Link to Review Status
common/tables/nova-zookeeper.xml (automatically generated) nova-zookeeper.rst Name Link to Review Status

Installation Guide Migration

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.

Chapter/Section (old filename) Chapter/Section (new filename) Name Patch URL Status
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
section_basics-packages.xml basics-packages.rst Karen Bradshaw https://review.openstack.org/#/c/203213/ Merged
section_basics-ntp.xml basics-ntp.rst Karen Bradshaw https://review.openstack.org/#/c/204182/ Merged
section_basics-networking.xml basics-networking.rst Karen Bradshaw https://review.openstack.org/#/c/204182/ Merged
section_basics-networking-neutron.xml basics-networking-neutron.rst Karen Bradshaw https://review.openstack.org/#/c/204182/ Merged
section_basics-networking-nova.xml basics-networking-nova.rst Karen Bradshaw https://review.openstack.org/#/c/204182/ Merged
section_basics-prerequisites.xml basics-prerequisites.rst Karen Bradshaw https://review.openstack.org/#/c/203213/ Merged
section_basics-database.xml basics-database.rst Karen Bradshaw https://review.openstack.org/#/c/199215/ Merged
section_basics-security.xml basics-security.rst Karen Bradshaw https://review.openstack.org/#/c/199215/ Merged
section_basics-queue.xml basics-queue.rst Karen Bradshaw https://review.openstack.org/#/c/199215/ Merged
ch_keystone.xml keystone.rst KATO Tomoyuki https://review.openstack.org/#/c/202110/ Merged
section_keystone-install.xml keystone-install.rst Harry Sutton https://review.openstack.org/#/c/205567/ Merged
section_keystone-services.xml keystone-services.rst Harry Sutton https://review.openstack.org/#/c/205569/ Merged
section_keystone-users.xml keystone-users.rst Harry Sutton https://review.openstack.org/#/c/205577/ Merged
section_keystone-verify.xml keystone-verify.rst KATO Tomoyuki https://review.openstack.org/#/c/202110/ Merged
section_keystone-openrc.xml keystone-openrc.rst KATO Tomoyuki https://review.openstack.org/#/c/202110/ Merged
ch_glance.xml glance.rst KATO Tomoyuki https://review.openstack.org/#/c/199964/ Merged
section_glance-install.xml glance-install.rst KATO Tomoyuki https://review.openstack.org/#/c/199964/ Merged
section_glance-verify.xml glance-verify.rst KATO Tomoyuki https://review.openstack.org/#/c/199964/ 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 https://review.openstack.org/#/c/198964/ Merged
section_nova-verify.xml nova-verify.rst KATO Tomoyuki https://review.openstack.org/#/c/198964/ Merged
ch_networking.xml networking.rst Karen Bradshaw https://review.openstack.org/#/c/204729/ Merged
section_neutron-concepts.xml neutron_concepts.rst Karen Bradshaw https://review.openstack.org/#/c/204729/ Merged
section_neutron-controller-node.xml neutron_controller_node.rst Brian Moss https://review.openstack.org/#/c/205347/ Merged
section_neutron-network-node.xml neutron_network_node.rst Brian Moss https://review.openstack.org/#/c/206274/ Merged
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_cinder.xml cinder.rst KATO Tomoyuki https://review.openstack.org/#/c/200767/ Merged
section_cinder-controller-node.xml cinder-controller-node.rst KATO Tomoyuki https://review.openstack.org/#/c/201225/ Merged
section_cinder-storage-node.xml cinder-storage-node.xml.rst KATO Tomoyuki https://review.openstack.org/#/c/201225/ Merged
section_cinder-verify.xml cinder-verify.rst KATO Tomoyuki https://review.openstack.org/#/c/200767/ Merged
ch_swift.xml swift.rst Christian Berendt https://review.openstack.org/#/c/195996/ Merged
section_swift-controller-node.xml swift_controller_node.rst Christian Berendt https://review.openstack.org/#/c/195996/ Merged
section_swift-finalize-installation.xml swift_finalize_installation.rst Christian Berendt https://review.openstack.org/#/c/195996/ Merged
section_swift-initial-rings.xml swift_initial_rings.rst Christian Berendt https://review.openstack.org/#/c/195996/ Merged
section_swift-storage-node.xml swift_storage_node.rst Christian Berendt https://review.openstack.org/#/c/195996/ Merged
section_swift-verify.xml swift_verify.rst Christian Berendt https://review.openstack.org/#/c/195996/ Merged
ch_heat.xml heat.rst KATO Tomoyuki https://review.openstack.org/#/c/199423/ Merged
section_heat-install.xml heat-install.rst KATO Tomoyuki https://review.openstack.org/#/c/199423/ Merged
section_heat-verify.xml heat-verify.rst KATO Tomoyuki https://review.openstack.org/#/c/199423/ Merged
ch_ceilometer.xml ceilometer.rst KATO Tomoyuki https://review.openstack.org/#/c/199796/ Merged
section_ceilometer-controller-install.xml ceilometer-controller-install.rst KATO Tomoyuki https://review.openstack.org/#/c/205090/ Merged
section_ceilometer-nova.xml ceilometer-nova.rst KATO Tomoyuki https://review.openstack.org/#/c/201016/ Merged
section_ceilometer-glance.xml ceilometer-glance.rst KATO Tomoyuki https://review.openstack.org/#/c/201016/ Merged
section_ceilometer-cinder.xml ceilometer-cinder.rst KATO Tomoyuki https://review.openstack.org/#/c/201016/ Merged
section_ceilometer-swift.xml ceilometer-swift.rst KATO Tomoyuki https://review.openstack.org/#/c/201016/ Merged
section_ceilometer-verify.xml ceilometer-verify.rst KATO Tomoyuki https://review.openstack.org/#/c/199796/ Merged
section_ceilometer_next_steps.xml ceilometer-next-steps.rst KATO Tomoyuki https://review.openstack.org/#/c/199796/ Merged
ch_launch-instance.xml launch-instance.rst KATO Tomoyuki https://review.openstack.org/#/c/200803/ Merged
section_launch-instance-neutron.xml launch-instance-neutron.rst KATO Tomoyuki https://review.openstack.org/#/c/200803/ Merged
section_launch-instance-nova.xml launch-instance-nova.rst KATO Tomoyuki https://review.openstack.org/#/c/200803/ Merged
app_reserved_uids.xml app-reserved-uids.rst Darren Chan https://review.openstack.org/#/c/204882/ Merged
ch_debconf.xml debconf.rst Karen Bradshaw https://review.openstack.org/#/c/205107/ Merged
section_debconf-concepts.xml debconf-concepts.rst Karen Bradshaw https://review.openstack.org/#/c/205107/ Merged
section_debconf-preseeding.xml debconf-concepts.rst Karen Bradshaw https://review.openstack.org/#/c/205107/ Merged
section_debconf-dbconfig-common.xml debconf-dbconfig-common.rst Brian Moss https://review.openstack.org/#/c/206870/ Merged
section_debconf-rabbitmq.xml debconf-rabbitmq.rst Brian Moss https://review.openstack.org/#/c/206870/ Merged
section_debconf-keystone_authtoken.xml debconf-keystone-authtoken.rst Brian Moss https://review.openstack.org/#/c/206870/ Merged
section_debconf-api-endpoints.xml debconf-api-endpoints.rst Brian Moss https://review.openstack.org/#/c/206870/ Merged
section_neutron-compute-node.xml neutron-compute-node.rst Brian Moss https://review.openstack.org/#/c/206277/ Merged
section_neutron-initial-networks.xml neutron-initial-networks.rst Brian Moss https://review.openstack.org/#/c/206299/ Merged
section_nova-networking-controller-node.xml networking-nova.rst Brian Moss https://review.openstack.org/#/c/206306/ Merged
section_nova-networking-compute-node.xml networking-nova.rst Brian Moss https://review.openstack.org/#/c/206306/ Merged
section_nova-networking-initial-network.xml networking-nova.rst Brian Moss https://review.openstack.org/#/c/206306/ Merged

Not being converted at this time:

  • ch_sahara.xml
  • section_sahara-install.xml
  • section_sahara-verify.xml
  • ch_trove.xml
  • section_trove-verify.xml

Doc Migration Plan

In Kilo we are migrating the End User Guide and the Admin User Guide. Refer to the 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:

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 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.

Completing conversion to RST

Note that this includes links to how it was done for the Security Guide as reference.

  1. Create a patch with the following steps: https://review.openstack.org/211766
    1. Delete old guide, here security-guide
    2. Move RST guide to location of new guide (security-guide-rst -> security-guide).
    3. Update tools/build-all-rst.sh for the change
    4. If the repository has no further DocBook guides in it, update tox.ini
    5. Update doc-tools-test-languages.conf
    6. Rename localization files to new directory name
    7. If there is a ".tx/config" file, update it (remove rst guide, update paths)
  2. If the repository has no further DocBook guides in it:
  3. 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
  4. 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
  5. Sync translations from old guide with new guide (needs to be done in transifex by Andreas)
  6. Tell i18n team that conversion is finished and which resource is active.
  7. Remove old guide and draft RST guides from docs.openstack.org (needs docs.openstack.org admin access)
  8. Regenerate sitemap.xml after all changes are in