Posted: Tue Apr 21, 2009 3:44 am Post subject: [asterisk-doc] PHP.net-style Asterisk Documentation
I was reading through the Feb 2009 archives for this list and found an exchange about setting up an "authoritative" documentation site for Asterisk. I think this would be a great complement to TFOT - especially once you get past the basics and want to really expand out a dialplan or a multi-server Asterisk PBX.
At work, we recently built a VOIP ACD using Asterisk, with a lot of dialplan logic that I would consider "advanced" - queueing, callback agents, agents on hard and soft phones, BLF lights and more. In the process of building this switch, we relied heavily on TFOT, Switching to VOIP and voip-info.org. That being said, it was still difficult to pin down decent documentation on how things can and should be done. Most of the time we used voip-info as a starting point and hacked around with a test system until we got something to work.
I agree that the voip-info wiki hasn't worked, and I'd be willing to help build a PHP.net-style documentation base with user-supplied comments. Is there still an interest in this?
I am also attempting to pick up the "clean up doxygen" janitoial project on Asterisk HEAD. If there is still an interest to build this system and pull the documentation straight out of the source code, I would be willing to help out with whatever coding needs to be done.
Posted: Tue Apr 21, 2009 4:08 am Post subject: [asterisk-doc] PHP.net-style Asterisk Documentation
On Mon, 20 Apr 2009, James Hunt wrote:
Quote:
I was reading through the Feb 2009 archives for this list and found an
exchange about setting up an "authoritative" documentation site for
Asterisk. I think this would be a great complement to TFOT - especially
once you get past the basics and want to really expand out a dialplan or a
multi-server Asterisk PBX.
At work, we recently built a VOIP ACD using Asterisk, with a lot of dialplan
logic that I would consider "advanced" - queueing, callback agents, agents
on hard and soft phones, BLF lights and more. In the process of building
this switch, we relied heavily on TFOT, Switching to VOIP and voip-info.org.
That being said, it was still difficult to pin down decent documentation on
how things can and should be done. Most of the time we used voip-info as a
starting point and hacked around with a test system until we got something
to work.
I agree that the voip-info wiki hasn't worked, and I'd be willing to help
build a PHP.net-style documentation base with user-supplied comments. Is
there still an interest in this?
I am also attempting to pick up the "clean up doxygen" janitoial project on
Asterisk HEAD. If there is still an interest to build this system and pull
the documentation straight out of the source code, I would be willing to
help out with whatever coding needs to be done.
Thoughts?
I built that in 2006 or 2007, but then business got too busy. The work
still sits in an svn repository at Digium -- search for my name in the
asterisk-doc archives and maybe the svn repository is there.
I agree -- better documentation is really needed. A moderated commenting
system, doxygen-imported information, and really just a better job of
in-depth docs on functionality is desperately needed. voip-info.org wiki
doesn't cut the mustard.
I can't offer help in the project unfortunately, but the base is there. I
simply copied the PHP documentation system from source back in 2006 or
2007, then updated it with Asterisk Dialplan Application documentation as
best I could.
---------------------------------------------------------------------------
Peter Beckman Internet Guy
beckman@angryox.comhttp://www.angryox.com/
---------------------------------------------------------------------------
_______________________________________________
--Bandwidth and Colocation Provided by http://www.api-digital.com--
Posted: Tue Apr 21, 2009 5:18 am Post subject: [asterisk-doc] PHP.net-style Asterisk Documentation
21 apr 2009 kl. 07.05 skrev Peter Beckman:
Quote:
On Mon, 20 Apr 2009, James Hunt wrote:
> I was reading through the Feb 2009 archives for this list and found
> an
> exchange about setting up an "authoritative" documentation site for
> Asterisk. I think this would be a great complement to TFOT -
> especially
> once you get past the basics and want to really expand out a
> dialplan or a
> multi-server Asterisk PBX.
>
> At work, we recently built a VOIP ACD using Asterisk, with a lot of
> dialplan
> logic that I would consider "advanced" - queueing, callback agents,
> agents
> on hard and soft phones, BLF lights and more. In the process of
> building
> this switch, we relied heavily on TFOT, Switching to VOIP and voip-
> info.org.
> That being said, it was still difficult to pin down decent
> documentation on
> how things can and should be done. Most of the time we used voip-
> info as a
> starting point and hacked around with a test system until we got
> something
> to work.
>
> I agree that the voip-info wiki hasn't worked, and I'd be willing
> to help
> build a PHP.net-style documentation base with user-supplied
> comments. Is
> there still an interest in this?
>
> I am also attempting to pick up the "clean up doxygen" janitoial
> project on
> Asterisk HEAD. If there is still an interest to build this system
> and pull
> the documentation straight out of the source code, I would be
> willing to
> help out with whatever coding needs to be done.
>
> Thoughts?
I built that in 2006 or 2007, but then business got too busy. The
work
still sits in an svn repository at Digium -- search for my name in the
asterisk-doc archives and maybe the svn repository is there.
I agree -- better documentation is really needed. A moderated
commenting
system, doxygen-imported information, and really just a better job of
in-depth docs on functionality is desperately needed. voip-info.org
wiki
doesn't cut the mustard.
Also note that there has been a lot of work going on to convert all
documentation
in the source code to XML format, in order to be able to automatically
build documentation sites, web help or windows help files.
/O
_______________________________________________
--Bandwidth and Colocation Provided by http://www.api-digital.com--
I was reading through the Feb 2009 archives for this list and found an exchange about setting up an "authoritative" documentation site for Asterisk. I think this would be a great complement to TFOT - especially once you get past the basics and want to really expand out a dialplan or a multi-server Asterisk PBX.
At work, we recently built a VOIP ACD using Asterisk, with a lot of dialplan logic that I would consider "advanced" - queueing, callback agents, agents on hard and soft phones, BLF lights and more. In the process of building this switch, we relied heavily on TFOT, Switching to VOIP and voip-info.org <http://voip-info.org/> . That being said, it was still difficult to pin down decent documentation on how things can and should be done. Most of the time we used voip-info as a starting point and hacked around with a test system until we got something to work.
I agree that the voip-info wiki hasn't worked, and I'd be willing to help build a PHP.net-style documentation base with user-supplied comments. Is there still an interest in this?
I am also attempting to pick up the "clean up doxygen" janitoial project on Asterisk HEAD. If there is still an interest to build this system and pull the documentation straight out of the source code, I would be willing to help out with whatever coding needs to be done.
Thoughts?
--
James
_______________________________________________
--Bandwidth and Colocation Provided by http://www.api-digital.com--
I was reading through the Feb 2009 archives for this list and found an exchange about setting up an "authoritative" documentation site for Asterisk. I think this would be a great complement to TFOT - especially once you get past the basics and want to really expand out a dialplan or a multi-server Asterisk PBX.
At work, we recently built a VOIP ACD using Asterisk, with a lot of dialplan logic that I would consider "advanced" - queueing, callback agents, agents on hard and soft phones, BLF lights and more. In the process of building this switch, we relied heavily on TFOT, Switching to VOIP and voip-info.org <http://voip-info.org/> . That being said, it was still difficult to pin down decent documentation on how things can and should be done. Most of the time we used voip-info as a starting point and hacked around with a test system until we got something to work.
I agree that the voip-info wiki hasn't worked, and I'd be willing to help build a PHP.net-style documentation base with user-supplied comments. Is there still an interest in this?
I am also attempting to pick up the "clean up doxygen" janitoial project on Asterisk HEAD. If there is still an interest to build this system and pull the documentation straight out of the source code, I would be willing to help out with whatever coding needs to be done.
Thoughts?
--
James
_______________________________________________
--Bandwidth and Colocation Provided by http://www.api-digital.com--
I was reading through the Feb 2009 archives for this list and found an
exchange about setting up an "authoritative" documentation site for
Asterisk. I think this would be a great complement to TFOT - especially
once you get past the basics and want to really expand out a dialplan or a
multi-server Asterisk PBX.
At work, we recently built a VOIP ACD using Asterisk, with a lot of dialplan
logic that I would consider "advanced" - queueing, callback agents, agents
on hard and soft phones, BLF lights and more. In the process of building
this switch, we relied heavily on TFOT, Switching to VOIP and voip-info.org.
That being said, it was still difficult to pin down decent documentation on
how things can and should be done. Most of the time we used voip-info as a
starting point and hacked around with a test system until we got something
to work.
I agree that the voip-info wiki hasn't worked, and I'd be willing to help
build a PHP.net-style documentation base with user-supplied comments. Is
there still an interest in this?
There is! And thanks for bringing this up, as I have been working on getting
this system up and running sooner rather than later. I hope within the next
month (or ideally less!) to get something like this up and running.
As Olle mentioned, there has been work to get things converted to XML
documentation inside the Asterisk code, so that is really the best place to
start. There are still some dialplan applications and functions that need to be
converted over, and then we need to start working on getting other areas using
this same type of documentation method for things like AMI commands, AGI
commands, CLI commands, etc...
Jared Smith has been working on some XML stuff recently so we can easily import
this into a CMS backend, so stay tuned in the near future for this all to be
released to the public.
When I have some extra work for the community to start participating in, you'll
hear about it on this mailing list.
Posted: Sun Apr 26, 2009 5:37 pm Post subject: [asterisk-doc] PHP.net-style Asterisk Documentation
On Tue, Apr 21, 2009 at 1:14 AM, Olle E. Johansson <oej@edvina.net> wrote:
Quote:
Also note that there has been a lot of work going on to convert all
documentation
in the source code to XML format, in order to be able to automatically
build documentation sites, web help or windows help files.
Is there anyone "in charge" of that effort that I could talk to? The
more I work with the LaTeX and doxygen documentation, the more I see
area for improvement that I would like to help out with.
I am assuming that by 'XML format' you mean something like DocBook for
the in-depth conceptual documentation / manuals. Is this correct?
--
James
_______________________________________________
--Bandwidth and Colocation Provided by http://www.api-digital.com--
On Sun, 2009-04-26 at 13:33 -0500, James Hunt wrote:
Quote:
Is there anyone "in charge" of that effort that I could talk to? The
more I work with the LaTeX and doxygen documentation, the more I see
area for improvement that I would like to help out with.
I don't know if there's really anyone "in charge" per se. Eliel
Sardañons did much of the initial implementation code in Asterisk, and
he and I (and a few others) have been slowing working to convert the
built-in help to the new format. I'd be happy to show you the ropes,
and I welcome any feedback and/or help along the way.
Quote:
I am assuming that by 'XML format' you mean something like DocBook for
the in-depth conceptual documentation / manuals. Is this correct?
It was decided that DocBook was too unwieldy to use for the internal
documentation, so we made a very simplified XML format that can be
easily converted to/from DocBook. If you were to use Subversion to
check out the trunk of Asterisk development, you'd see that the DTD for
our format is included with Asterisk.
-Jared
_______________________________________________
--Bandwidth and Colocation Provided by http://www.api-digital.com--
On Mon, Apr 27, 2009 at 9:36 AM, Jared Smith <jaredsmith@jaredsmith.net> wrote:
Quote:
I don't know if there's really anyone "in charge" per se. Eliel
Sardañons did much of the initial implementation code in Asterisk, and
he and I (and a few others) have been slowing working to convert the
built-in help to the new format. I'd be happy to show you the ropes,
and I welcome any feedback and/or help along the way.
That would be great.
Quote:
It was decided that DocBook was too unwieldy to use for the internal
documentation, so we made a very simplified XML format that can be
easily converted to/from DocBook. If you were to use Subversion to
check out the trunk of Asterisk development, you'd see that the DTD for
our format is included with Asterisk.
I did some looking in trunk, and I did find the XML itself. This actually ties
into the PHP.net-style asterisk docs site -- I think we can extract the XML
and use it to create a web node for each application / function / etc., and
then slap a commenting engine on top of it.
I'll look for the DTD tonight.
--
James
_______________________________________________
--Bandwidth and Colocation Provided by http://www.api-digital.com--
On Mon, 2009-04-27 at 10:09 -0500, James Hunt wrote:
Quote:
I did some looking in trunk, and I did find the XML itself. This actually ties
into the PHP.net-style asterisk docs site -- I think we can extract the XML
and use it to create a web node for each application / function / etc., and
then slap a commenting engine on top of it.
That's the goal... but after spending way too much time looking at the
php.net code, I think we'll end up building some other app rather than
using their code.
The first item of business, however, is to make sure that each and every
application is converted over to the new format, and to clean up the
documentation along the way. From there it should be pretty simple to
create web output.
(I've even got a simple XSL transform for creating HTML output from the
AstXML documentation... once I have a few more bugs worked out of it,
I'll post it for all to see.)
-Jared
_______________________________________________
--Bandwidth and Colocation Provided by http://www.api-digital.com--
On Mon, Apr 27, 2009 at 10:27 AM, Jared Smith <jaredsmith@jaredsmith.net> wrote:
Quote:
That's the goal... but after spending way too much time looking at the
php.net code, I think we'll end up building some other app rather than
using their code.
Excellent. I've done a fair bit of web development in the Rails and PHP arena,
so if I can help out with the backend engine, I'd be glad to. I am also a Linux
sysad by profession and passion, so if any help is needed running the web box,
I would also be happy to assist.
Quote:
The first item of business, however, is to make sure that each and every
application is converted over to the new format, and to clean up the
documentation along the way. From there it should be pretty simple to
create web output.
I think the two efforts could work in parallel - one team starts hacking on the
web engine to build the pages from source and tack on the comment structure,
and another starts reviewing the quality and scope of the source docs.
Ideally, we want to make it as easy as possible to update the web docs from
the latest stable source code, without implementing hooks from the VCS repo.
It would be awesome if the web engine was smart enough to allow admins to
initiate a docs rebuild, which would go out and check out latest stable, extract
the XML docs and refresh the site with current stuff. We could even place a
version tag in the header of the website, to let people know how current the web
docs really are.
Quote:
(I've even got a simple XSL transform for creating HTML output from the
AstXML documentation... once I have a few more bugs worked out of it,
I'll post it for all to see.)
Looking forward to it.
--
James
_______________________________________________
--Bandwidth and Colocation Provided by http://www.api-digital.com--
You cannot post new topics in this forum You cannot reply to topics in this forum You cannot edit your posts in this forum You cannot delete your posts in this forum You cannot vote in polls in this forum
FAQ
Search
Memberlist
Usergroups
Register
Profile
Log in to check your private messages
Log in
