From miconda@gmail.com Mon Mar 25 17:50:40 2013
From: Daniel-Constantin Mierla <miconda@gmail.com>
To: sr-dev@lists.kamailio.org
Subject: [sr-dev] Help improving the modules readmes & docs
Date: Mon, 25 Mar 2013 17:50:30 +0100
Message-ID: <51508056.6080909@gmail.com>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="===============1640693431=="

--===============1640693431==
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 7bit

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 -



--===============1640693431==--


From hugh.waite@crocodile-rcs.com Fri Apr  5 12:51:14 2013
From: Hugh Waite <hugh.waite@crocodile-rcs.com>
To: sr-dev@lists.kamailio.org
Subject: Re: [sr-dev] Help improving the modules readmes & docs
Date: Fri, 05 Apr 2013 11:51:08 +0100
Message-ID: <515EAC9C.8040308@crocodile-rcs.com>
In-Reply-To: <51508056.6080909@gmail.com>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="===============1993369782=="

--===============1993369782==
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 7bit

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>

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?

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">?

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
>


-- 
Hugh Waite
Principal Design Engineer
Crocodile RCS Ltd.



--===============1993369782==--


From miconda@gmail.com Fri Apr  5 13:52:45 2013
From: Daniel-Constantin Mierla <miconda@gmail.com>
To: sr-dev@lists.kamailio.org
Subject: Re: [sr-dev] Help improving the modules readmes & docs
Date: Fri, 05 Apr 2013 13:52:35 +0200
Message-ID: <515EBB03.6020208@gmail.com>
In-Reply-To: <515EAC9C.8040308@crocodile-rcs.com>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="===============0719029633=="

--===============0719029633==
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 7bit

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 -



--===============0719029633==--