I've created some perl scripts that generate documentation (both in txt and docbook format) from the cfg vars, RPCs and select declarations in the code. The RPCs and cfg vars include also the doc strings. The selects are only listed (more then that cannot be automatically extracted, but at least their name is self-explaining in 99% of the cases). The scripts (for now only in the andrei/cdefs2doc branch) require a non-standard perl module (GCC::TranslationUnit) with one extra patch to it and take a lot of time to execute. Because of this I think it would be much better to also have the generated documentation in the repository, in the xml and .txt format (it would add 500k-1Mb of docs).
Examples:
html generated from the auto-generated docbook xmls: http://sip-router.org/docbook/sip-router/branch/andrei/cdefs2doc/cfg_list/cf... http://sip-router.org/docbook/sip-router/branch/andrei/cdefs2doc/rpc_list/rp... http://sip-router.org/docbook/sip-router/branch/andrei/cdefs2doc/select_list...
txt output for the cfg vars: http://git.sip-router.org/cgi-bin/gitweb.cgi?p=sip-router;a=blob;f=doc/cfg_l...
example of an auto-generated xml: http://git.sip-router.org/cgi-bin/gitweb.cgi?p=sip-router;a=blob;f=doc/rpc_l...
(note that the above example were generated from older code and not from the latest master or 3.0 versions)
If you have an idea for better formatting, please provide a short xml example.
If nobody speaks against it, I will merge the branch into master next week and start to re-generate the docs periodically.
Andrei P.S.: for the perl scripts see http://git.sip-router.org/cgi-bin/gitweb.cgi?p=sip-router;a=tree;f=doc/scrip...
That's great. IMO we should add it (just like the READMEs)
thanks klaus
Andrei Pelinescu-Onciul wrote:
I've created some perl scripts that generate documentation (both in txt and docbook format) from the cfg vars, RPCs and select declarations in the code. The RPCs and cfg vars include also the doc strings. The selects are only listed (more then that cannot be automatically extracted, but at least their name is self-explaining in 99% of the cases). The scripts (for now only in the andrei/cdefs2doc branch) require a non-standard perl module (GCC::TranslationUnit) with one extra patch to it and take a lot of time to execute. Because of this I think it would be much better to also have the generated documentation in the repository, in the xml and .txt format (it would add 500k-1Mb of docs).
Examples:
html generated from the auto-generated docbook xmls: http://sip-router.org/docbook/sip-router/branch/andrei/cdefs2doc/cfg_list/cf... http://sip-router.org/docbook/sip-router/branch/andrei/cdefs2doc/rpc_list/rp... http://sip-router.org/docbook/sip-router/branch/andrei/cdefs2doc/select_list...
txt output for the cfg vars: http://git.sip-router.org/cgi-bin/gitweb.cgi?p=sip-router;a=blob;f=doc/cfg_l...
example of an auto-generated xml: http://git.sip-router.org/cgi-bin/gitweb.cgi?p=sip-router;a=blob;f=doc/rpc_l...
(note that the above example were generated from older code and not from the latest master or 3.0 versions)
If you have an idea for better formatting, please provide a short xml example.
If nobody speaks against it, I will merge the branch into master next week and start to re-generate the docs periodically.
Andrei P.S.: for the perl scripts see http://git.sip-router.org/cgi-bin/gitweb.cgi?p=sip-router;a=tree;f=doc/scrip...
sr-dev mailing list sr-dev@lists.sip-router.org http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-dev
-
Andrei Pelinescu-Onciul -
Henning Westerholt -
Klaus Darilion