OpenStack Compute (nova)

Confusing compute extensions documentation

Bug #965335 reported by John Kennedy
6
This bug affects 1 person
Affects Status Importance Assigned to Milestone
OpenStack Compute (nova)
Fix Released
Undecided
John Kennedy
OpenStack Compute (nova) 2012.1 "essex"

Bug Description

The Extensions subsection of the page http://nova.openstack.org/api_ext/index.html is unclear the way it is currently rendered.

Although extension developers are using the correct template doc/source/api_ext/rst_extension_template.rst, they are not all editing the first line "About This Extension" and so the extension name is not visible on the documentation page above.

Also, "Summary of Changes" is at the same level in the hierarchy as "About This Extension". A single top level bullet for each extension would be more intuitive.

A suggested fix is to update the template page so that
 - top line is extension name only (and make it obvious it must be edited)
 - there is an "About This Extension" sub section containing existing content
 - demote "Summary of Changes" so that it appears at same level as the new "About This Extension" sub-section, below the level of the name of this extension

Existing extension documentation pages would then have to be updated to make them consistent.

John Kennedy (john-m-kennedy)
Changed in nova:
assignee: nobody → John Kennedy (john-m-kennedy)
status: New → In Progress
Revision history for this message
Anne Gentle (annegentle) wrote :

Agreed, have been meaning to log a similar bug. Would love changes beyond just the template.

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix proposed to nova (master)

Fix proposed to branch: master
Review: https://review.openstack.org/5995

Revision history for this message
John Kennedy (john-m-kennedy) wrote :

Fix committed, including existing docs + reference to ext_aggregates.rst doc in index.rst which seemed to be missing. *Everything* new to me...hope I didn't break anything.

Changed in nova:
status: In Progress → Fix Committed
Vish Ishaya (vishvananda)
tags: added: essex-rc-potential
Revision history for this message
Vish Ishaya (vishvananda) wrote :

officially Fix Committed gets set automatically once the change is merged so you don't need to set it yourself. It is about to go in anyway so I will leave it for now.

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix merged to nova (master)

Reviewed: https://review.openstack.org/5995
Committed: http://github.com/openstack/nova/commit/a68156c100022b9d1e5640ed532b0c734e422c38
Submitter: Jenkins
Branch: master

commit a68156c100022b9d1e5640ed532b0c734e422c38
Author: John Kennedy <email address hidden>
Date: Fri Mar 30 14:23:22 2012 +0100

    bug 965335

    Resolves unclear formatting of compute extensions documentation at
    http://nova.openstack.org/api_ext/index.html

    The rst extensions template has been updated to include extension name as
    top level hierarchy, and demote all other content.

    All existing documentation pages have been reformatted as per the updated
    template.

    The ext_aggreagates.rst file has also been added to index.rst.

    Amendments:
     - Author added to Authors file
     - Typo in ext_volumes.rst fixed

    Change-Id: Id67ef91a6e8eaaf4fba46abbd57759c77aaf8991

Revision history for this message
John Kennedy (john-m-kennedy) wrote :

Thanks Vish - I misunderstood. I thought it was for when I commit my proposed fix to my branch for review.

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix proposed to nova (milestone-proposed)

Fix proposed to branch: milestone-proposed
Review: https://review.openstack.org/6047

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix merged to nova (milestone-proposed)

Reviewed: https://review.openstack.org/6047
Committed: http://github.com/openstack/nova/commit/9473de7c95b3776646c457429cc733925679d45a
Submitter: Jenkins
Branch: milestone-proposed

commit 9473de7c95b3776646c457429cc733925679d45a
Author: John Kennedy <email address hidden>
Date: Fri Mar 30 14:23:22 2012 +0100

    bug 965335

    Resolves unclear formatting of compute extensions documentation at
    http://nova.openstack.org/api_ext/index.html

    The rst extensions template has been updated to include extension name as
    top level hierarchy, and demote all other content.

    All existing documentation pages have been reformatted as per the updated
    template.

    The ext_aggreagates.rst file has also been added to index.rst.

    Amendments:
     - Author added to Authors file
     - Typo in ext_volumes.rst fixed

    Change-Id: Id67ef91a6e8eaaf4fba46abbd57759c77aaf8991

Changed in nova:
status: Fix Committed → Fix Released
Thierry Carrez (ttx)
Changed in nova:
milestone: none → 2012.1
To post a comment you must log in.
This report contains Public information  
Everyone can see this information.
Subscribing...

Other bug subscribers

Remote bug watches

Bug watches keep track of this bug in other bug trackers.