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 -