[SR-Users] Kamailio KEMI Framework Tutorial

[Daniel-Constantin Mierla]

Hello,


On 22.11.17 19:47, Samuel F. wrote:
>
> Hi again,
>
>
> Regarding RPC list: I do not think it is implemented for python?
>
it is not, indeed, I just looked at the code. I am not much into python
myself, so it was overlooked -- I just added kemi support for it on top
of the previous app_python.

> I checked the source and couldn't find anything that would handle the
> RPC call:
>
> kamctl rpc app_python.api_list
>
>
> Regarding the documentation:
> I didn't mean to document in the source code, sorry for not expressing
> myself clearly,

That was a proposal on the IRC devel meeting to add doxygen docs for
kemi function, which is good to have anyhow, but for something with more
details and examples, doxygen can become a mess.

>  I ment to generate the Kemi function list documentation from the
> source code automatically via a script instead of updating it manually
> (so the documentation doesn't become stale). One example could be to
> run the RPC api_list and take that list to generate a documentation
> file that shows all available functions. I tried to check that out now
> but couldn't get it working for python because I think the command is
> missing (v5.0.4).
>
> So to condense my proposal on how we could structure the KEMI docs I
> would suggest:
> - General documentation about how KEMI works: As it is now, great
> - Document special functions that are only implemented in KEMI /or
> differs from the original module implementation: As it is now, great
> - Not have sections for each and every module, just one section with a
> long list of exported KEMI functions with a link to the original
> documentation
>
> I'm happy to take a shot at generating a script for this but would
> need help to understand how I can export the python API list.

I am going to add the rpc command to app_python, then you can try to
build your tool for it.

Cheers,
Daniel

>
> // Samuel
>
> ------------------------------------------------------------------------
> *From:* Daniel-Constantin Mierla <miconda at gmail.com>
> *Sent:* Tuesday, November 21, 2017 3:20:21 PM
> *To:* Samuel F.; Kamailio (SER) - Users Mailing List
> *Subject:* Re: [SR-Users] Kamailio KEMI Framework Tutorial
>  
>
> Hello,
>
>
> On 21.11.17 10:20, Samuel F. wrote:
>>
>> Hi Daniel,
>>
>>
>> First, I'd just like to say thanks and let you know we are very
>> grateful for the KEMI framework. We have developed three
>> small applications running on python KEMI in production serving calls
>> every day successfully without any issues at all. The development
>> process was very smooth and quick.
>>
>
> thanks for the feedback, really appreciated! It is good to know that
> KEMI is being used in production and also it shows its potential for
> various needs.
>
>>
>> I reviewed the documentation and think it's great that the KEMI
>> framework gets an extensive documentation.
>>
>>
>> One thought I had regarding documenting the exported functions is
>> that I think it's good if they are exported to the docs automatically
>> from the source code. My opinion is that it is better to have
>> documentation that reflects the current state of the source code
>> rather than having stale/out-of-date documentation.
>>
>>
>> Perhaps having a parser that locates all the exported functions,
>> lists them in appropriate modules with the return value and then a
>> link to the actual modules documentation?
>>
>
> There is an RPC command that lists the exported KEMI functions for a
> running Kamailio. It reflects exactly what functions are available
> from the kemi framework internal structure. This is like an auto
> discovery, it is done automatically.
>
> Addition docs can be added in the code using doxygen, however, while
> that is good for short descriptions, I don't find it good to add
> extensive docs and especially usage examples in the code. Also, from
> past experiences, non-developer users tend not to look at the code,
> therefore the improvements to docs in code from general users are very
> low.
>
> Anyhow, this tutorial was started with the initial goal of covering
> the KEMI framework in general, and the special functions. For the
> functions exported by modules I added only the acc as an example
> (which is also a skeleton at this moment).
>
> As I said, I am open for suggestions on how to do the docs for kemi
> functions from modules. Your proposal with using somehow the code is
> not like being dismissed, I just expressed my opinions based.
> Contributions to parse the code and extract prototypes are of course
> welcome.
>
> Cheers,
> Daniel
>
>
>>
>> // Samuel
>>
>> ------------------------------------------------------------------------
>> *From:* sr-users <sr-users-bounces at lists.kamailio.org>
>> <mailto:sr-users-bounces at lists.kamailio.org> on behalf of
>> Daniel-Constantin Mierla <miconda at gmail.com> <mailto:miconda at gmail.com>
>> *Sent:* Monday, November 20, 2017 4:11:54 PM
>> *To:* Kamailio (SER) - Users Mailing List; Kamailio (SER) - Devel
>> Mailing List
>> *Subject:* [SR-Users] Kamailio KEMI Framework Tutorial
>>  
>> Hello,
>>
>> I started a tutorial for Kamailio KEMI Framework written in markdown
>> format targeting use of mkdocs. It is published on github as part of
>> kamailio-docs repository:
>>
>>   *
>> https://nam02.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fkamailio%2Fkamailio-docs%2Ftree%2Fmaster%2Fkamailio-kemi-framework&data=02%7C01%7Csamuel_is_kewl%40hotmail.com%7C226fe2242ed4436c13fa08d53029444d%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636467876150276887&sdata=MuTy1ZgjcDEbQdHTGA2LpO1sKUDAxxo%2BupwGr%2BBspCE%3D&reserved=0
>>
>> The mkdocs build (to browse and read) is online at:
>>
>>   *
>> https://nam02.safelinks.protection.outlook.com/?url=http%3A%2F%2Fkamailio.org%2Fdocs%2Ftutorials%2Fdevel%2Fkamailio-kemi-framework%2F&data=02%7C01%7Csamuel_is_kewl%40hotmail.com%7C226fe2242ed4436c13fa08d53029444d%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636467876150276887&sdata=FHJ1zANtLQI6o2%2F1wFPFYfu1B94JlQ%2FHTLDbaVp7dUg%3D&reserved=0
>>
>> It is work in progress and contributions from the community are more
>> than welcome -- doing push requests on github project is the recommended
>> way for contributions:
>>
>>   *
>> https://nam02.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fkamailio%2Fkamailio-docs%2F&data=02%7C01%7Csamuel_is_kewl%40hotmail.com%7C226fe2242ed4436c13fa08d53029444d%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636467876150276887&sdata=utRI9tOvpEuyBWFU70KaBaod6URNk0ju4rTSQl%2FhO3I%3D&reserved=0
>>
>> The main goal is document the role of KEMI, its benefits and how it can
>> be used. It addition it should cover the list of functions exported to
>> KEMI by core as well as special KEMI functions.
>>
>> Regarding the functions exported by kamailio modules to KEMI I added as
>> an skeleton the ones exported by acc module. However, I am not sure if
>> we should do it there or add them to the existing docs of the modules.
>> Opinions on this?!?
>>
>> Cheers,
>> Daniel
>>
>> -- 
>> Daniel-Constantin Mierla
>> https://nam02.safelinks.protection.outlook.com/?url=www.twitter.com%2Fmiconda&data=02%7C01%7Csamuel_is_kewl%40hotmail.com%7C226fe2242ed4436c13fa08d53029444d%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636467876150276887&sdata=%2F1Fg1476daehbTE4jVNmQ1%2BQro52j%2Fy6maGN8HZmHjU%3D&reserved=0
>> --
>> https://nam02.safelinks.protection.outlook.com/?url=www.linkedin.com%2Fin%2Fmiconda&data=02%7C01%7Csamuel_is_kewl%40hotmail.com%7C226fe2242ed4436c13fa08d53029444d%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636467876150276887&sdata=WytUIkS%2FT0cdu%2BEMhSLz8TFhkn2PADOVGEjnHF5d2lE%3D&reserved=0
>> Kamailio Advanced Training -
>> https://nam02.safelinks.protection.outlook.com/?url=www.asipto.com&data=02%7C01%7Csamuel_is_kewl%40hotmail.com%7C226fe2242ed4436c13fa08d53029444d%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636467876150276887&sdata=b8D9EWNFf5eocdwbjZDu8nKmFF777nNE5yknicVgDKs%3D&reserved=0
>> Kamailio World Conference - May 14-16, 2018 -
>> https://nam02.safelinks.protection.outlook.com/?url=www.kamailioworld.com&data=02%7C01%7Csamuel_is_kewl%40hotmail.com%7C226fe2242ed4436c13fa08d53029444d%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636467876150276887&sdata=X7KEbj5w3kLSiCPrpgnrdoCITpeBiWPfAeYFyY2yMhk%3D&reserved=0
>>
>>
>> _______________________________________________
>> Kamailio (SER) - Users Mailing List
>> sr-users at lists.kamailio.org <mailto:sr-users at lists.kamailio.org>
>> https://nam02.safelinks.protection.outlook.com/?url=https%3A%2F%2Flists.kamailio.org%2Fcgi-bin%2Fmailman%2Flistinfo%2Fsr-users&data=02%7C01%7Csamuel_is_kewl%40hotmail.com%7C226fe2242ed4436c13fa08d53029444d%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636467876150276887&sdata=HLJ5knbTzvZ2EFRpdNEPawUUy5ArJVL6HVqitepIM2Q%3D&reserved=0
>
> -- 
> Daniel-Constantin Mierla
> www.twitter.com/miconda
> <https://eur02.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.twitter.com%2Fmiconda&data=02%7C01%7Csamuel_is_kewl%40hotmail.com%7Cb0ef8c659a014ebc3bbc08d530eb0520%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636468708318318423&sdata=%2B6XNLL0f7NWcJWExn7P%2FBQSdjfry6ku79GWr1C9HFyA%3D&reserved=0> -- www.linkedin.com/in/miconda
> <https://eur02.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.linkedin.com%2Fin%2Fmiconda&data=02%7C01%7Csamuel_is_kewl%40hotmail.com%7Cb0ef8c659a014ebc3bbc08d530eb0520%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636468708318318423&sdata=gctVv3a%2Fyt6K%2F5u8cdxDPOVCXpjAFtWYWdi0edqlQaE%3D&reserved=0>
> Kamailio Advanced Training - www.asipto.com
> <https://eur02.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.asipto.com&data=02%7C01%7Csamuel_is_kewl%40hotmail.com%7Cb0ef8c659a014ebc3bbc08d530eb0520%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636468708318318423&sdata=PUjvVlxZ6%2B6i%2BVX1uyHDP7EHF4dbYgozNjlFRJMJICg%3D&reserved=0>
> Kamailio World Conference - May 14-16, 2018 - www.kamailioworld.com
> <https://eur02.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.kamailioworld.com&data=02%7C01%7Csamuel_is_kewl%40hotmail.com%7Cb0ef8c659a014ebc3bbc08d530eb0520%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636468708318318423&sdata=n7wEMwvt38VIugGTLcT9mBZMNLCCaeWgYKDWtapcnVc%3D&reserved=0>

-- 
Daniel-Constantin Mierla
www.twitter.com/miconda -- www.linkedin.com/in/miconda
Kamailio Advanced Training - www.asipto.com
Kamailio World Conference - May 14-16, 2018 - www.kamailioworld.com

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.kamailio.org/pipermail/sr-users/attachments/20171123/a8b9f779/attachment.html>