[sr-dev] Help improving the modules readmes & docs

[Daniel-Constantin Mierla]

Hello,

On 4/5/13 12:51 PM, Hugh Waite wrote:
> Hi,
> I've added a new event route to the tm module and would like to 
> document it in the README. (I've already added it to the wiki)
> With regards to providing automatic indexing, can we standardise a 
> 'type' for the event_route section of documentation.
> For example 'e':
> <section id="tm.e.branch-failure">
> ...
> </section>
>
it is ok, we can reserve e for event routes. I created a page on wiki to 
collect guidelines about wrinting docbook files for README:

- https://www.kamailio.org/wiki/devel/module-docbook-readme

Anyone feel free to add there.


> Also, the tm module docs are split into separate xml files, with a 
> top-level section <section id="tm.functions" ...>. Should this format 
> be kept and does there need to be a standard for the top-level section 
> ids?

My interest was initially for the elements that are referred in 
alphabetic indexes, the rest is more a decision of the developer, but if 
done it should try to keep a pattern.
>
> Finally, I'm adding the id's to the websocket module where the MI 
> commands include a dot e.g. "ws.enable". Does this affect the id 
> generation, should it be replaced with underscore <section 
> id="websocket.m.ws_enable">?
I think is ok to keep it as the name, not replacing with '_', the prefix 
is important to have unique names across modules and inside modules (in 
eventuality there is a function named xyz and a rpc command xyz).

Cheers,
Daniel

>
> Regards,
> Hugh
>
>
> On 25/03/2013 16:50, Daniel-Constantin Mierla wrote:
>> Hello,
>>
>> I thought some people may have spare cycles and are willing to help 
>> with the documentation. Here is some updates I would like to get for 
>> modules:
>>
>> 1) adding ids for parameters, functions, and other sections of the 
>> docbook xml files. Now we generate the alphabetic indexes pointing to 
>> the online html readmes, would be better to point directly to the 
>> exact section. Practically, for example, sections such as next from 
>> async module:
>>
>>    <section>
>>         <title><varname>workers</varname> (int)</title>
>>
>> should become:
>>
>>    <section id="async.p.workers">
>>         <title><varname>workers</varname> (int)</title>
>>
>> To get unique ids over all files, I suggest using following pattern:
>>
>> [module name] [dot] [type] [dot] [title]
>>
>> The [type] should be:
>> - p - parameters
>> - f - functions
>> - m - mi commands
>> - r - rpc commands
>> - s - statistics
>>
>> 2) Add RPC commands to readmes -- some of modules already do, but 
>> many don't. There is a perl script that should get the list of RPC 
>> commands from source code, but it requires some patch to a perl lib, 
>> not working on all systems. Moreover, the output is quite 
>> minimalistic, not easy to improve the content or add examples. Last 
>> generated index is:
>>
>> - http://www.kamailio.org/docs/docbooks/3.4.x/rpc_list/rpc_list.html
>>
>> 3) Document selects -- although their name are quite suggestive, a 
>> bit of text around won't harm.
>>
>> - http://www.kamailio.org/wiki/cookbooks/devel/selects
>>
>> Because 1) and 2) requires git access, the easiest way to contribute 
>> is to provide patches to the xml files. If anyone commits to do an 
>> extensive work on these tasks in short term, we may eventually 
>> arrange for git access. The 3) is in the wiki, everyone can register 
>> an account and then update the pages.
>>
>> I would recommend these guidelines to be followed from now on by 
>> developers when adding new elements to the module documentation.
>>
>> Cheers,
>> Daniel
>>
>
>

-- 
Daniel-Constantin Mierla - http://www.asipto.com
http://twitter.com/#!/miconda - http://www.linkedin.com/in/miconda
Kamailio World Conference, April 16-17, 2013, Berlin
  - http://conference.kamailio.com -