doxygen-users

[Doxygen-users] Adding Custom Commands to execute Shell Scripts

[Rosen D. <ros...@gm...>]

dear doxygen users,

It would be really great to be able to define a custom command in
doxygen that can execute a program on the shell and directly insert
its output into the doxygen parser. I was thinking this would be
possible with the ALIASES command, but only recursively replaces text,
it doesn't do any shell execution.

Therefore, what do you think about the proposal of adding a \shell
command to doxygen? For example:

\shell "progname args"

Where progname could hypothetically run several examples on my
project, where each example generates images according to the "args"
of the program; the stdout output will be a set of "\image html
xxx.png" strings, which doxygen would happily parse and insert into
the documentation.

Looking at the doxygen sources, the use of "portable_system" function
is pretty common, combining that with the aliases feature, we could
have a \shell command completed fairly quickly..

thanks,
rosen diankov,

Re: [Doxygen-users] Adding Custom Commands to execute Shell Scripts

[Rosen D. <ros...@gm...>]

hi all,

Just curious, any ideas about adding such a feature.  I was thinking
it would be also possible to use it for syntax highlighting of
languages beyond c++. even though our project is written in c++, it
provides bindings to several other languages, so it would be really
cool if we can put that code in doxygen and have a \shell command that
runs on the args and outputs html code. There's a really awesome
syntax highlighter for this called python-pygments
(http://pygments.org/), so all that's missing is the doxygen part.

I realize there is an INPUT_FILTER configuration, but I would really
hate to have to spoon-feed doxygen this way.

thanks,
rosen,

2010/7/15 Rosen Diankov <ros...@gm...>:
> dear doxygen users,
>
> It would be really great to be able to define a custom command in
> doxygen that can execute a program on the shell and directly insert
> its output into the doxygen parser. I was thinking this would be
> possible with the ALIASES command, but only recursively replaces text,
> it doesn't do any shell execution.
>
> Therefore, what do you think about the proposal of adding a \shell
> command to doxygen? For example:
>
> \shell "progname args"
>
> Where progname could hypothetically run several examples on my
> project, where each example generates images according to the "args"
> of the program; the stdout output will be a set of "\image html
> xxx.png" strings, which doxygen would happily parse and insert into
> the documentation.
>
> Looking at the doxygen sources, the use of "portable_system" function
> is pretty common, combining that with the aliases feature, we could
> have a \shell command completed fairly quickly..
>
> thanks,
> rosen diankov,
>

Re: [Doxygen-users] Adding Custom Commands to execute Shell Scripts

[Adam N. <a.n...@sh...>]

> I realize there is an INPUT_FILTER configuration, but I would really
> hate to have to spoon-feed doxygen this way.
> 
>> Therefore, what do you think about the proposal of adding a \shell
>> command to doxygen? For example:
>>
>> \shell "progname args"

Couldn't you use INPUT_FILTER to write a parser that runs these \shell
commands instead?  How would you make the commands platform independent
anyway?  (e.g. can you tie in your autoconf scripts to replace program paths
to account for differences between user PCs?)

Cheers,
Adam.

Re: [Doxygen-users] Adding Custom Commands to execute Shell Scripts

[Rosen D. <ros...@gm...>]

> Couldn't you use INPUT_FILTER to write a parser that runs these \shell
> commands instead?

that means we would need to run a lexer and figure out the comments,
and then parse the language tags. do you know of such a script? a
\shell tag is so much easier and natural.

i'm not sure why we are talking about 'platform independent'
documentation generation when clearly doxygen is filled with many
interesting features that execute shell commands at a user's demand,
like the INPUT_FILTER configuration. anyway, the information we put in
our doxygen comments and how we generate the actual documentation
heavily depends on our environment, even though our project is
platform independent...

as my original email said, all doxygen has to do is pass the "progname
args" to the portable_system function.

rosen,

2010/7/18 Adam Nielsen <a.n...@sh...>:
>> I realize there is an INPUT_FILTER configuration, but I would really
>> hate to have to spoon-feed doxygen this way.
>>
>>> Therefore, what do you think about the proposal of adding a \shell
>>> command to doxygen? For example:
>>>
>>> \shell "progname args"
>
> Couldn't you use INPUT_FILTER to write a parser that runs these \shell
> commands instead?  How would you make the commands platform independent
> anyway?  (e.g. can you tie in your autoconf scripts to replace program paths
> to account for differences between user PCs?)
>
> Cheers,
> Adam.
>

Re: [Doxygen-users] Adding Custom Commands to execute Shell Scripts

[Adam N. <a.n...@sh...>]

>> Couldn't you use INPUT_FILTER to write a parser that runs these \shell
>> commands instead?
> 
> that means we would need to run a lexer and figure out the comments,
> and then parse the language tags. do you know of such a script? a
> \shell tag is so much easier and natural.

Depends how flexible you need it to be.  Unless you want to run hundreds of
different shell commands you could just replace it with some generic tokens
like $OUTPUT_GOES_HERE and then use sed or something in INPUT_FILTER to do a
search and replace with the output of some predefined commands.  The advantage
there being if you change one of the programs that generates the output, you
only need to update your INPUT_FILTER script rather than hundreds of \shell
commands scattered throughout the docs/code.

> i'm not sure why we are talking about 'platform independent'
> documentation generation when clearly doxygen is filled with many
> interesting features that execute shell commands at a user's demand,
> like the INPUT_FILTER configuration.

Executing shell commands isn't a problem, but shell scripts usually run
external programs and these can be configured differently on different
systems.  That's why autoconf and other build environments have tests to make
sure programs exist, are the correct versions, etc.  I would imagine that in
an ideal world INPUT_FILTER would call a local script which has been generated
as part of the configure process.

> anyway, the information we put in
> our doxygen comments and how we generate the actual documentation
> heavily depends on our environment, even though our project is
> platform independent...

Hope your documentation generation procedure is well documented then ;-)

> as my original email said, all doxygen has to do is pass the "progname
> args" to the portable_system function.

Well if it's that simple I'm sure a patch would be cheerfully accepted :-)

Cheers,
Adam.

Re: [Doxygen-users] Adding Custom Commands to execute Shell Scripts

[Rosen D. <ros...@gm...>]

hi adam,

Thanks for the feedback. Here is our current documentation:

http://openrave.programmingvision.com/ordocs/english/html/index.html

As you can see, it needs a lot of work to make it something like
(http://matplotlib.sourceforge.net/gallery.html).

I think the simplest and fastest way for me would be just add the
feature in the C++ code and send a patch.

Because i want things done correctly, the INPUT_FILTER is very
difficult for many reasons; i would have to create a parser for a
subset of doxygen. If it was just a matter of simply replacing
$OUTPUT_GOES_HERE, then ALIASES would be more than enough.

As for the rest of your comments:

- Although we provide all scripts, we have no interest in users being
able to build their own documentation.

- we use cmake, not autotools

- we want all information/example code pertaining to a particular
module in one location, the source file.

- Let me worry about \shell commands being scattered throughout our project ;0)

- ALIASES can always be used to wrap the \shell commands.

rosen,

2010/7/18 Adam Nielsen <a.n...@sh...>:
>>> Couldn't you use INPUT_FILTER to write a parser that runs these \shell
>>> commands instead?
>>
>> that means we would need to run a lexer and figure out the comments,
>> and then parse the language tags. do you know of such a script? a
>> \shell tag is so much easier and natural.
>
> Depends how flexible you need it to be.  Unless you want to run hundreds of
> different shell commands you could just replace it with some generic tokens
> like $OUTPUT_GOES_HERE and then use sed or something in INPUT_FILTER to do a
> search and replace with the output of some predefined commands.  The advantage
> there being if you change one of the programs that generates the output, you
> only need to update your INPUT_FILTER script rather than hundreds of \shell
> commands scattered throughout the docs/code.
>
>> i'm not sure why we are talking about 'platform independent'
>> documentation generation when clearly doxygen is filled with many
>> interesting features that execute shell commands at a user's demand,
>> like the INPUT_FILTER configuration.
>
> Executing shell commands isn't a problem, but shell scripts usually run
> external programs and these can be configured differently on different
> systems.  That's why autoconf and other build environments have tests to make
> sure programs exist, are the correct versions, etc.  I would imagine that in
> an ideal world INPUT_FILTER would call a local script which has been generated
> as part of the configure process.
>
>> anyway, the information we put in
>> our doxygen comments and how we generate the actual documentation
>> heavily depends on our environment, even though our project is
>> platform independent...
>
> Hope your documentation generation procedure is well documented then ;-)
>
>> as my original email said, all doxygen has to do is pass the "progname
>> args" to the portable_system function.
>
> Well if it's that simple I'm sure a patch would be cheerfully accepted :-)
>
> Cheers,
> Adam.
>

Re: [Doxygen-users] Adding Custom Commands to execute Shell Scripts

[Eric J. H. <er...@ho...>]

On 7/18/2010 7:42 AM, Rosen Diankov wrote:
>
> Because i want things done correctly, the INPUT_FILTER is very
> difficult for many reasons; i would have to create a parser for a
> subset of doxygen. If it was just a matter of simply replacing
> $OUTPUT_GOES_HERE, then ALIASES would be more than enough.
>
>    

I think you're not understanding something.  Why do you
need to parse any syntax at all?

If the commands look like $OUTPUT_GOES_HERE ('cat /etc/passwd')

can't you just write a simple filter that looks for the token 
$OUTPUT_GOES_HERE
then gathers everything between the parens, execs your command,
captures the output, and replaces it?

What doxygen (or c++) syntax do you need to parse?

Re: [Doxygen-users] Adding Custom Commands to execute Shell Scripts

[Rosen D. <ros...@gm...>]

There are two things:

- have to make sure we are in a c++ comment, this is tricky due to strings
and the  preprocessor. Accidentally replacing code could affect the
structure of the classes.

- we paste code in the comments in verbatim blocks in doxygen. I do not want
anything being accidentally repalced there.

Rosen,

On Jul 18, 2010 9:40 AM, "Eric J. Holtman" <er...@ho...> wrote:

On 7/18/2010 7:42 AM, Rosen Diankov wrote:
>
> Because i want things done correctly, the INPUT_FILTE...
I think you're not understanding something.  Why do you
need to parse any syntax at all?

If the commands look like $OUTPUT_GOES_HERE ('cat /etc/passwd')

can't you just write a simple filter that looks for the token
$OUTPUT_GOES_HERE
then gathers everything between the parens, execs your command,
captures the output, and replaces it?

What doxygen (or c++) syntax do you need to parse?


------------------------------------------------------------------------------
This SF.net email is sponsored by Sprint
What will you do first with EVO, the first 4G phone?
Visit sprint.com/first -- http://p.sf.net/sfu/sprint-com-first
_______________________________________________
Doxygen-users mailing list
Dox...@li...
https://lists.sourceforge.net/lists/listinfo/doxygen-users

Re: [Doxygen-users] Adding Custom Commands to execute Shell Scripts

[Rosen D. <ros...@gm...>]

Hi all,

I wasn't sure what message to take from the last email responses.

Does everyone agree that a \shell command would be awesome, and we
just don't have someone to add this feature.

Or is everyone on the side of doing some magic with INPUT_FILTER and a
\shell command is really a bad idea?

thanks,
rosen,

2010/7/18 Rosen Diankov <ros...@gm...>:
> There are two things:
>
> - have to make sure we are in a c++ comment, this is tricky due to strings
> and the  preprocessor. Accidentally replacing code could affect the
> structure of the classes.
>
> - we paste code in the comments in verbatim blocks in doxygen. I do not want
> anything being accidentally repalced there.
>
> Rosen,
>
> On Jul 18, 2010 9:40 AM, "Eric J. Holtman" <er...@ho...> wrote:
>
> On 7/18/2010 7:42 AM, Rosen Diankov wrote:
>>
>> Because i want things done correctly, the INPUT_FILTE...
>
> I think you're not understanding something.  Why do you
> need to parse any syntax at all?
>
> If the commands look like $OUTPUT_GOES_HERE ('cat /etc/passwd')
>
> can't you just write a simple filter that looks for the token
> $OUTPUT_GOES_HERE
> then gathers everything between the parens, execs your command,
> captures the output, and replaces it?
>
> What doxygen (or c++) syntax do you need to parse?
>
>
> ------------------------------------------------------------------------------
> This SF.net email is sponsored by Sprint
> What will you do first with EVO, the first 4G phone?
> Visit sprint.com/first -- http://p.sf.net/sfu/sprint-com-first
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>

Re: [Doxygen-users] Adding Custom Commands to execute Shell Scripts

[Eric J. H. <er...@ho...>]

On 7/23/2010 8:17 AM, Rosen Diankov wrote:
> What happens if I have a '(' or ')' in the command? Does that mean
> that I cannot document the "$OUTPUT_THIS_COMMAND" itself because it is
> a reserved keyword? I also want to use ALIASES and have arguments to
> the alias that I should pass into $OUTPUT_THIS_COMMAND, how does that
> work?
>
>    

Ah.... you want to pass arguments.    Well, then, I think you'll
need your \shell extension

> Obviously, you are a much better programmer and know your way around
> such scripts, so it would be greatly appreciated if you can help with
> this trivial script... perhaps even put it somewhere on the doxygen
> website so others don't have to struggle?
>
>    

I apologize, Rosen.   I thought you really just wanted to execute fixed
commands.  If you want more than that, I think you'll need your
extension.