yahoo-eng-team team mailing list archive

[Dolph Mathews <1402824@xxxxxxxxxxxxxxxxxx>]

Public bug reported:

A significant portion of the API documentation consists of attribute
definition lists, wherein a literal attribute is defined with one or
more paragraphs of text, and may contain additional documentation for
child attributes.

In the conversion from markdown to restructuredtext, all of these
paragraphs have become separated from the attributes being defined, such
that you can't necessarily tell where one attribute ends, and another
begins.

Additional minor issues as a result of the conversion include:

- Some lists being rendered as literal blocks:
  https://github.com/openstack/keystone-specs/blob/master/api/v3/identity-api-v3.rst#endpoints-v3endpoints

- Some lists that were not in proper markdown format now appear as paragraphs of unbroken text (see query parameters):
  https://github.com/openstack/keystone-specs/blob/master/api/v3/identity-api-v3-os-trust-ext.rst#list-trusts

- Paragraphs not being wrapped at 79 characters (only visible in source)

** Affects: keystone
     Importance: Medium
     Assignee: Dolph Mathews (dolph)
         Status: Triaged


** Tags: documentation

** Tags added: documentation

** Changed in: keystone
     Assignee: (unassigned) => Dolph Mathews (dolph)

** Changed in: keystone
   Importance: Undecided => Medium

** Changed in: keystone
       Status: New => Triaged

-- 
You received this bug notification because you are a member of Yahoo!
Engineering Team, which is subscribed to Keystone.
https://bugs.launchpad.net/bugs/1402824

Title:
  Conversion of API specs from MD to RST resulted in bad formatting

Status in OpenStack Identity (Keystone):
  Triaged

Bug description:
  A significant portion of the API documentation consists of attribute
  definition lists, wherein a literal attribute is defined with one or
  more paragraphs of text, and may contain additional documentation for
  child attributes.

  In the conversion from markdown to restructuredtext, all of these
  paragraphs have become separated from the attributes being defined,
  such that you can't necessarily tell where one attribute ends, and
  another begins.

  Additional minor issues as a result of the conversion include:

  - Some lists being rendered as literal blocks:
    https://github.com/openstack/keystone-specs/blob/master/api/v3/identity-api-v3.rst#endpoints-v3endpoints

  - Some lists that were not in proper markdown format now appear as paragraphs of unbroken text (see query parameters):
    https://github.com/openstack/keystone-specs/blob/master/api/v3/identity-api-v3-os-trust-ext.rst#list-trusts

  - Paragraphs not being wrapped at 79 characters (only visible in
  source)

To manage notifications about this bug go to:
https://bugs.launchpad.net/keystone/+bug/1402824/+subscriptions