API documentation does not conform to Namespace URL paths

[Matt Joyce]

API methods have unique identifiers defined as a namespace in them.

Below is an example class definition for the flavormanage API, in it you can see the namespace definition pointing to a docs path.

It would be worthwhile to make sure that documentation on method calls is accessible at that namespace URL.

Otherwise there's 300 some odd namespace pathes in the source that will 404. Also at a later date this namespace identifier could be used to ensure that any newly registered namespace has corresponding documentation provided and updated ( on deltas ) as a test case.

Example class in API:

class Flavormanage(extensions.ExtensionDescriptor):
    """
    Flavor create/delete API support
    """

    name = "FlavorManage"
    alias = "os-flavor-manage"
    namespace = ("http://docs.openstack.org/compute/ext/"
                 "flavor_manage/api/v1.1")
    updated = "2012-01-19T00:00:00+00:00"

    def get_controller_extensions(self):
        controller = FlavorManageController()
        extension = extensions.ControllerExtension(self, 'flavors', controller)
        return [extension]
~

[Tom Fifield (fifieldt)]

Hi,

So what should be at that URL?

Would a link to an anchor within the api.openstack.org site be sufficient ?

eg http://docs.openstack.org/compute/ext/flavor_manage/api/v1.1 points to http://api.openstack.org#flavour-manage

[Tom Fifield (fifieldt)]

(just FYI these anchors don't exist right now)

[Matt Joyce (matt-nycresistor)]

so the namespace definitions are as far as I can tell used solely to prevent a name space collision in API ref urls.

I say point those URLs at the documentation for the individual method calls.

Then we can test case against that URL to confirm there is documentation for the method before passing.

[Tom Fifield (fifieldt)]

Ok - so what we would need to do then, is create a new site with one page per extension.

It's doable, but fiddly :)

[Anne Gentle (annegentle)]

Wanted to add a note that bug 1064645 is related, though not quite a duplicate.

[Anne Gentle (annegentle)]

Currently devs are managing without these resolving to real web pages. Due to not having resources, marking Won't Fix.