Api doc categories

[Marcus Sorensen <sh...@gmail.com>]

I've spent a few minutes trying to figure out how API commands are linked
with their categories in the API documentation. I read the doc about
annotations and generating the docs. I see the known_categories in
gen_toc.py, but I don't see any place in the annotations where one might
define a specific command under a specific category. When I build I do see
it complain about uncategorized commands, such as the ones in the netapp
plugin (or whatever provides the 'filer' commands).

Re: Api doc categories

[Marcus Sorensen <sh...@gmail.com>]

I've confirmed that mismatches can happen, for example if you say both
VPN and VPC in an api name. It would be nice to have an explicit
annotation for doc category.

On Thu, Aug 22, 2013 at 10:41 AM, Marcus Sorensen <sh...@gmail.com> wrote:
> Thanks, in looking through the mail history, I can see various
> suggestions of adding categories to gen_toc.py, but I don't see a
> concrete explanation of how this works. In experimenting it seems that
> the category is matched against the api command name. That seems quite
> limiting from a third party perspective, it means that vendors
> offering plugins have to encode the category in the api name of every
> command if they want it to fall under a specific category.
>
> If this is true, it would be nice to have an optional category field
> in the annotations to avoid mismatches. Take the netapp commands, for
> example, some of them are things like 'associateLun', while others are
> like 'listVolumesOnFiler'. An argument could be made that they need to
> be renamed to include the word 'netapp', but as it stands, they might
> create a netapp category and match anything with 'Lun' or 'Filer',
> then when someone else comes along those keywords are taken.
>
> On Thu, Aug 22, 2013 at 3:04 AM, Daan Hoogland <da...@gmail.com> wrote:
>> Marcus,
>>
>> I recall a mail in this list where a naming convention was mentioned.
>> Look along those lines for categories.
>>
>> regards,
>> Daan
>>
>> On Thu, Aug 22, 2013 at 6:46 AM, Marcus Sorensen <sh...@gmail.com> wrote:
>>> I've spent a few minutes trying to figure out how API commands are linked
>>> with their categories in the API documentation. I read the doc about
>>> annotations and generating the docs. I see the known_categories in
>>> gen_toc.py, but I don't see any place in the annotations where one might
>>> define a specific command under a specific category. When I build I do see
>>> it complain about uncategorized commands, such as the ones in the netapp
>>> plugin (or whatever provides the 'filer' commands).

Re: Api doc categories

[Marcus Sorensen <sh...@gmail.com>]

Thanks, in looking through the mail history, I can see various
suggestions of adding categories to gen_toc.py, but I don't see a
concrete explanation of how this works. In experimenting it seems that
the category is matched against the api command name. That seems quite
limiting from a third party perspective, it means that vendors
offering plugins have to encode the category in the api name of every
command if they want it to fall under a specific category.

If this is true, it would be nice to have an optional category field
in the annotations to avoid mismatches. Take the netapp commands, for
example, some of them are things like 'associateLun', while others are
like 'listVolumesOnFiler'. An argument could be made that they need to
be renamed to include the word 'netapp', but as it stands, they might
create a netapp category and match anything with 'Lun' or 'Filer',
then when someone else comes along those keywords are taken.

On Thu, Aug 22, 2013 at 3:04 AM, Daan Hoogland <da...@gmail.com> wrote:
> Marcus,
>
> I recall a mail in this list where a naming convention was mentioned.
> Look along those lines for categories.
>
> regards,
> Daan
>
> On Thu, Aug 22, 2013 at 6:46 AM, Marcus Sorensen <sh...@gmail.com> wrote:
>> I've spent a few minutes trying to figure out how API commands are linked
>> with their categories in the API documentation. I read the doc about
>> annotations and generating the docs. I see the known_categories in
>> gen_toc.py, but I don't see any place in the annotations where one might
>> define a specific command under a specific category. When I build I do see
>> it complain about uncategorized commands, such as the ones in the netapp
>> plugin (or whatever provides the 'filer' commands).

Re: Api doc categories

[Daan Hoogland <da...@gmail.com>]

Marcus,

I recall a mail in this list where a naming convention was mentioned.
Look along those lines for categories.

regards,
Daan

On Thu, Aug 22, 2013 at 6:46 AM, Marcus Sorensen <sh...@gmail.com> wrote:
> I've spent a few minutes trying to figure out how API commands are linked
> with their categories in the API documentation. I read the doc about
> annotations and generating the docs. I see the known_categories in
> gen_toc.py, but I don't see any place in the annotations where one might
> define a specific command under a specific category. When I build I do see
> it complain about uncategorized commands, such as the ones in the netapp
> plugin (or whatever provides the 'filer' commands).