You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cloudstack.apache.org by "SuichII, Christopher" <Ch...@netapp.com> on 2013/11/04 17:19:12 UTC
[DISCUSS] Add 'Other' category to gen_toc.py for apidoc
I would like to be able to leverage the existing apidoc tools to generate apidoc for my plugin’s exposed APIs. However, gen_toc.py expects all APIs to fall into one of the hard coded ‘known_categories’. Since my APIs don’t fall into one of the existing categories, gen_toc.py fails with the error:
Exception: Need to add a category for <my api> to gen_toc.py:known_categories
What are people’s thoughts on adding a category called ‘Other’ for APIs which do not fall into one of the hard coded categories? I’ve tested this locally by adding the following to gen_toc.py:
To the end of the known_categories hash: 'Other' : ‘Other’
At end end of choose_category(fn): return known_categories['Other’]
I think there is a lot to be done with the apidoc tools moving forward to allow third party plugins to use the tools, but this would be a quick fix that would at least make the tools usable for now.
-Chris
--
Chris Suich
chris.suich@netapp.com<ma...@netapp.com>
NetApp Software Engineer
Data Center Platforms – Cloud Solutions
Citrix, Cisco & Red Hat
Re: [DISCUSS] Add 'Other' category to gen_toc.py for apidoc
Posted by "SuichII, Christopher" <Ch...@netapp.com>.
Agreed. I’m not a fan of how this is working right now, but this late in the cycle I think trying to rework all of this is a scary idea. It would be a good thing to look for post-4.3.
-Chris
--
Chris Suich
chris.suich@netapp.com
NetApp Software Engineer
Data Center Platforms – Cloud Solutions
Citrix, Cisco & Red Hat
On Nov 4, 2013, at 11:29 AM, Chip Childers <ch...@apache.org> wrote:
> On Mon, Nov 04, 2013 at 04:19:12PM +0000, SuichII, Christopher wrote:
>> I would like to be able to leverage the existing apidoc tools to generate apidoc for my plugin’s exposed APIs. However, gen_toc.py expects all APIs to fall into one of the hard coded ‘known_categories’. Since my APIs don’t fall into one of the existing categories, gen_toc.py fails with the error:
>>
>> Exception: Need to add a category for <my api> to gen_toc.py:known_categories
>>
>> What are people’s thoughts on adding a category called ‘Other’ for APIs which do not fall into one of the hard coded categories? I’ve tested this locally by adding the following to gen_toc.py:
>>
>> To the end of the known_categories hash: 'Other' : ‘Other’
>> At end end of choose_category(fn): return known_categories['Other’]
>>
>> I think there is a lot to be done with the apidoc tools moving forward to allow third party plugins to use the tools, but this would be a quick fix that would at least make the tools usable for now.
>>
>> -Chris
>
> I've not been a fan of that particular configuration file personally.
> IMO, if that works, then great. We should revisit removing that config
> file requirement altogether though.
>
> -chip
Re: [DISCUSS] Add 'Other' category to gen_toc.py for apidoc
Posted by Chip Childers <ch...@apache.org>.
On Mon, Nov 04, 2013 at 04:19:12PM +0000, SuichII, Christopher wrote:
> I would like to be able to leverage the existing apidoc tools to generate apidoc for my plugin’s exposed APIs. However, gen_toc.py expects all APIs to fall into one of the hard coded ‘known_categories’. Since my APIs don’t fall into one of the existing categories, gen_toc.py fails with the error:
>
> Exception: Need to add a category for <my api> to gen_toc.py:known_categories
>
> What are people’s thoughts on adding a category called ‘Other’ for APIs which do not fall into one of the hard coded categories? I’ve tested this locally by adding the following to gen_toc.py:
>
> To the end of the known_categories hash: 'Other' : ‘Other’
> At end end of choose_category(fn): return known_categories['Other’]
>
> I think there is a lot to be done with the apidoc tools moving forward to allow third party plugins to use the tools, but this would be a quick fix that would at least make the tools usable for now.
>
> -Chris
I've not been a fan of that particular configuration file personally.
IMO, if that works, then great. We should revisit removing that config
file requirement altogether though.
-chip