Quantcast

Q: possible to create custom special pages?

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Q: possible to create custom special pages?

Albrecht Dreß
Hi all,

Is it possible in doxygen to create a custom "todo"-like list from other commands?  E.g. something like the "side effects" custom command documented here [1], with the addition, that all these "side effects" paragraphs are collected somewhere?

For a practical use case, consider a software where changes are added by many people which must be reviewed.  Everyone should add a special comment (e.g. "@review", as custom command) briefly documenting the changes.  If those changes are all collected on a special page, and cross-referenced to the description, this would greatly simplify a review process.

Thanks in advance,
Albrecht.


[1] <http://www.stack.nl/~dimitri/doxygen/manual/custcmd.html#custcmd_simple>
------------------------------------------------------------------------------
Attend Shape: An AT&T Tech Expo July 15-16. Meet us at AT&T Park in San
Francisco, CA to explore cutting-edge tech and listen to tech luminaries
present their vision of the future. This family event has something for
everyone, including kids. Get more information and register today.
http://sdm.link/attshape
_______________________________________________
Doxygen-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users

attachment0 (484 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Q: possible to create custom special pages?

Monique Semp
> Is it possible in doxygen to create a custom "todo"-like list from other
> commands? ... Everyone should add a special comment (e.g. "@review", as
> custom command) briefly documenting the changes.  If those changes are all
> collected on a special page, and cross-referenced to the description, this
> would greatly simplify a review process.

Yes, it's possible, and it's easier than the documentation makes it seem.

I have several of these lists that I use for things as varied as
@todo_techpubs, @todo_eng_review (for things I want to highlight as needing
review), @todo_add_ask (for public entities that I'm unsure about
documenting, because there are public entities that are nevertheless not for
end user use, but are needed by internal modules.

I'll use the @todo_eng_review example since it corresponds most closely to
your use case.

In the Doxyfile, I have the following alias (the ending "\" chars are so
that I can have linefeeds in the Doxyfile for easier readability, but you
could put the entire command on a single line):

ALIASES               += todo_eng_review="@xrefitem key_todo_eng_review \
                           \"Eng Review\" \"Eng Review Requested List\" \
                           Eng-review requested."

And you need to set the GENERATE_TODOLIST = YES.

Then when  you use the @todo_eng_review command in the Doxygen comment
blocks, you'll get a page for the Eng Review Requested List.

I generally have two versions of my Doxyfile config files: one for a
review/non-release/internal version that sets "GENERATE_TODOLIST = YES", and
one that's for the actual production version where we don't want to expose
these internal things to the end user, with "GENERATE_TODOLIST = NO". This
way I don't have to strip out all these comments from the code, and can
carry things over to the next version.

If you go this route, then in addition to having "GENERATE_TODOLIST = NO",
you need to change the ALIAS, which I do as follows:

ALIASES               += todo_eng_review="@todo Eng-review requested."

I found this necessary because the GENERATE_TODOLIST applies only to the
@todo comments, not the @todo_eng_review. So if I don't redefine the
@todo_eng_review back to @todo, I end up with that separate @xrefitem page
appearing in the output.

A bonus bit of info: I wanted these special @todo things to stand out in the
output, with a magenta vertical bar instead of the regular color. I created
a customdoxygen.css stylesheet, set "HTML_EXTRA_STYLESHEET =
customdoxygen.css", and in in the stylesheet, after the dl.todo entry, I
added an entry for dl.todo_eng_review. I kept everything the same as the
regular dl.todo, except for the color:

dl.key_todo_eng_review
{
        margin-left:-7px;
        padding-left: 3px;
        border-left:4px solid;
        border-color: #FF00FF;    /* magenta */
}

HTH,
-Monique





------------------------------------------------------------------------------
Attend Shape: An AT&T Tech Expo July 15-16. Meet us at AT&T Park in San
Francisco, CA to explore cutting-edge tech and listen to tech luminaries
present their vision of the future. This family event has something for
everyone, including kids. Get more information and register today.
http://sdm.link/attshape
_______________________________________________
Doxygen-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Q: possible to create custom special pages?

Monique Semp
Oh, I forgot to say that I'm using Doxygen 1.8.10, but I think this is
pretty standard across many Doxygen versions.


------------------------------------------------------------------------------
Attend Shape: An AT&T Tech Expo July 15-16. Meet us at AT&T Park in San
Francisco, CA to explore cutting-edge tech and listen to tech luminaries
present their vision of the future. This family event has something for
everyone, including kids. Get more information and register today.
http://sdm.link/attshape
_______________________________________________
Doxygen-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Q: possible to create custom special pages?

albert
In reply to this post by Albrecht Dreß
Albrecht,

Please look in the manual at \xrefitem or search the internet for some examples.
This question has popped up multiple times on e.g. this forum and on stackexchange.

Albert

On Fri, Jun 24, 2016 at 7:15 PM, Albrecht Dreß <[hidden email]> wrote:
Hi all,

Is it possible in doxygen to create a custom "todo"-like list from other commands?  E.g. something like the "side effects" custom command documented here [1], with the addition, that all these "side effects" paragraphs are collected somewhere?

For a practical use case, consider a software where changes are added by many people which must be reviewed.  Everyone should add a special comment (e.g. "@review", as custom command) briefly documenting the changes.  If those changes are all collected on a special page, and cross-referenced to the description, this would greatly simplify a review process.

Thanks in advance,
Albrecht.


[1] <http://www.stack.nl/~dimitri/doxygen/manual/custcmd.html#custcmd_simple>
------------------------------------------------------------------------------
Attend Shape: An AT&T Tech Expo July 15-16. Meet us at AT&T Park in San
Francisco, CA to explore cutting-edge tech and listen to tech luminaries
present their vision of the future. This family event has something for
everyone, including kids. Get more information and register today.
http://sdm.link/attshape
_______________________________________________
Doxygen-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users



------------------------------------------------------------------------------
Attend Shape: An AT&T Tech Expo July 15-16. Meet us at AT&T Park in San
Francisco, CA to explore cutting-edge tech and listen to tech luminaries
present their vision of the future. This family event has something for
everyone, including kids. Get more information and register today.
http://sdm.link/attshape
_______________________________________________
Doxygen-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

hard to search - the archives on sourceforge...

Monique Semp
> This question has popped up multiple times on e.g. this forum and on stackexchange.
Yes, but... I find it very (very) hard to use the archives on sourceforge. Unlike the archives of many other lists I’ve subscribed to, I haven’t found a way to search for a topic and then display all a given message’s replies in a typical threaded view. Clicking on individual messages often result in a display with the message repeated at least twice, but no links to the previous or next messages in a thread.
 
It’s been a long time since the list moved to sourceforge, but I believe that the archives were much easier to search before that.
 
But occasionally when I click a message, I do see several responses. I just have no idea when it’ll “work” and when I have to keep going to the search page and searching for ever-more specific things to try to get the display to show me all a thread’s messages.
 
Perhaps I’m doing something wrong, or there’s a setting I haven’t found?
 
-Monique
 

------------------------------------------------------------------------------
Attend Shape: An AT&T Tech Expo July 15-16. Meet us at AT&T Park in San
Francisco, CA to explore cutting-edge tech and listen to tech luminaries
present their vision of the future. This family event has something for
everyone, including kids. Get more information and register today.
http://sdm.link/attshape
_______________________________________________
Doxygen-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: hard to search - the archives on sourceforge...

albert
Monique,

It is indeed hard to search but quite often I have quite good success with google (not only for doxygen) on stack exchange buy giving as first word stack followed by some keywords.

Albert

On Fri, Jun 24, 2016 at 7:56 PM, Monique Semp <[hidden email]> wrote:
> This question has popped up multiple times on e.g. this forum and on stackexchange.
Yes, but... I find it very (very) hard to use the archives on sourceforge. Unlike the archives of many other lists I’ve subscribed to, I haven’t found a way to search for a topic and then display all a given message’s replies in a typical threaded view. Clicking on individual messages often result in a display with the message repeated at least twice, but no links to the previous or next messages in a thread.
 
It’s been a long time since the list moved to sourceforge, but I believe that the archives were much easier to search before that.
 
But occasionally when I click a message, I do see several responses. I just have no idea when it’ll “work” and when I have to keep going to the search page and searching for ever-more specific things to try to get the display to show me all a thread’s messages.
 
Perhaps I’m doing something wrong, or there’s a setting I haven’t found?
 
-Monique
 

------------------------------------------------------------------------------
Attend Shape: An AT&T Tech Expo July 15-16. Meet us at AT&T Park in San
Francisco, CA to explore cutting-edge tech and listen to tech luminaries
present their vision of the future. This family event has something for
everyone, including kids. Get more information and register today.
http://sdm.link/attshape
_______________________________________________
Doxygen-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users



------------------------------------------------------------------------------
Attend Shape: An AT&T Tech Expo July 15-16. Meet us at AT&T Park in San
Francisco, CA to explore cutting-edge tech and listen to tech luminaries
present their vision of the future. This family event has something for
everyone, including kids. Get more information and register today.
http://sdm.link/attshape
_______________________________________________
Doxygen-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Q: possible to create custom special pages?

Albrecht Dreß
In reply to this post by albert
Am 24.06.16 19:41 schrieb(en) Albert:
> Please look in the manual at \xrefitem or search the internet for some examples.

Ouch.  Looks as if I didn't read the right section of the manual.  Sorry for the noise!

Monique, thanks a lot for your excellent example - works perfectly for me, exactly what I need! :-)

Sorry again,
Albrecht.
------------------------------------------------------------------------------
Attend Shape: An AT&T Tech Expo July 15-16. Meet us at AT&T Park in San
Francisco, CA to explore cutting-edge tech and listen to tech luminaries
present their vision of the future. This family event has something for
everyone, including kids. Get more information and register today.
http://sdm.link/attshape
_______________________________________________
Doxygen-users mailing list
[hidden email]
https://lists.sourceforge.net/lists/listinfo/doxygen-users

attachment0 (484 bytes) Download Attachment
Loading...