Allow the SVN Code Browser to link to appropriate Doxy Docs.

[doxygenplugin@…]

Hi,

I've just enabled the doxygen plugin on my trac install and kudos to both of you developers.

It's mega handy as it is but I have a suggestion for an enhancement that you can perhaps think about (I'm not a Python coder so don't really know how hard this is).

In my code project, I use the wiki to document certain parts of our code such that new employees/contractors can easily read though it and find out some of the core aspects of our code - e.g. data validation routines, class factories etc. As part of this documentation, I frequently use the source: macro to link directly to the files in question. It would be really nice if this also linked to the Doxygen docs too. - e.g. the source code browser knew about doxygen and which sub path within SVN the Doxy docs were generated from. It could then give a "See Doxygen Documentation for this file" type links directly from the source broswer.

As the Doxy generated HTML files are rather criptic, I cannot see how to do this easily without making the macro itself a little cleverer. I'm sure the information needed will be in one of the files Doxy generates (e.g. the search index file??).

Thanks for listening and for such a cool plugin. If I've not explained myself very well, I apologise - just ask and I will attempt to clarify.

[Radek Bartoň]

Hello.

Your feature could be usefull so I don't see reason why won't implement it. You actually derscribed two ways how to implement it: First is to edit [source:<file> <desc>] macro to show i. e. two link <desc> (doc) or secound to edit whole source browser module to cointain links to doxygen documentation. First soulution would be more easier as I think but secound is more universal. Consider yourself what is best for you and let me know. I'm preparing for thee day trip so I can start working on that on Tuesday earliest.

[doxygenplugin@…]

Hi

Thanks for looking at this :)

As for hacking the [source:<file> <desc>] macro, I don't think that is a good idea personally. There are probably legitimate reasons to link just to a source file without the documentation and vice versa. So I think a separate macro to link to docs is more sensible and that way you get full flexibility. Here are my thoughts:

• Ability to define a variable "Repo path to Doc Root" which tells the Code Browser at which path to start generating doxygen links.
• Keep the [source:] macro as standard
• Enhance the [doxygen:] macro to look for documention root files (if you want to make it more flexible it could also look to see if the path you specify has "Repo path to Doc Root" at the begining and strip it off, that way the user would not get confused if he inadvertantly uses the wrong path)

Example

My doxydocs are generated from a check out of trunk/myproject/code

• My "Repo path to Doc Root" variable is thus trunk/myproject/code
• If I use the Browse Source option of trac, when I browse to this path, Doxygen links start appearing automatically for each file.
• Assuming the code folder has a file src/main.cc:
  • If I use the macro [doxygen:src/main.cc] this would link to the documentation for that file.
  • For convenience [doxygen:trunk/myproject/code/src/main.cc] would also do the same thing (as the macro detected that the link started with "Repo path to Doc Root" value.

Does that make sense?

[doxygenplugin@…]

Thought of a couple other things:

It would be good if the [doxygen:] macro could also link directly to class docs, interface docs, functions etc. too.

As the macro is getting cleverer, here's what I would suggest it does:

1. Check to see if there is some html file exists and link to it if it does.
2. Failing above, check to see if some doxgen file reference exists (with or without the "Repo path to Doc Root" variable at the front).
3. Failing above, checks to see if a class exists by that name and go directly to the class documentation.
4. As above for interface.
5. As above for funtion.
6. Fails by presenting a page saying it cannot find anything to directly link to and ask the user if they way to do a search for that term instead.

I guess it wouldn't be the macro itself doing these checks (fairly large load for that), but the doxygen controller (don't know if "controller" is the correct term here). I'm guessing if I visited http://www.mytrac.com/doxygen/myClass that it would redirect me (via HTTP 302?) to the class documentation HTML file for myClass.

[Radek Bartoň]

Ok, thats sounds more clearer to me. Impmementing of [doxygen:] macro "intelligence" would be first step. I'll leave source browser editing in the later for now.

[Radek Bartoň]

Do you have some documenation with interfaces publicly accesible?

[doxygenplugin@…]

Unfortunately not, I don't have any publically available doxygen docs. I guess you could grab the actual source of doxygen and try that. Don't know if it has any "interfaces" in the program construct sense if that's what you meant tho'. If class and function names work I'd be happy as I don't have any projects that use interfaces ;)

[Radek Bartoň]

I've commited changeset 1129 with "intelligent" documentation referencing. This is the way how it shoud work:

• If no documetation directory in request is specified it should look into <path> + <default_documentation> directory if default_documentation config option is setted or in <path> directory if it is not.

• If documentation file with extension specified by ext config option is requested then it is returned directly.
• If source file with extension specified by source_ext config option is requested then apropriate documenation for this source file is returned.
• If request ends with class name then documentation for it is returned.
• If request ends with structure name then documentation for it is returned.
• If request end with something else then searching for that term is performed. If there is found exact phrase then documenation for that is returned (i. e. /doxygen/MyProject/MyClass::MyFunction).
• Search results is returned otherwise.

I hope that this behaviour satisfy you need and if not please tell me. Testing is welcome too.

[Colin Guthrie]

Looks good. I'll take it for a whirl sometime very soon and see if I can break it >:)

Thanks for this. It will come in very handy.

[Radek Bartoň]

What about documentation link in source browser, do you still want this feature? I think that it would have form of Trac source code patch.

[Christian Boos]

Replying to Blackhex:

What about documentation link in source browser, do you still want this feature? I think that it would have form of Trac source code patch.

Related to ​#T1781. We could probably make an extension point for this, e.g.

class BrowserRelatedPathProvider(Interface):
    def get_related_path(req, repos, path):
        """Generator yielding (name, tooltip, url) tuples for links of interest
        in relation with the currently browsed path."""

[Radek Bartoň]

Replying to cboos:

Replying to Blackhex:

What about documentation link in source browser, do you still want this feature? I think that it would have form of Trac source code patch.

Related to ​#T1781. We could probably make an extension point for this, e.g.

class BrowserRelatedPathProvider(Interface):
    def get_related_path(req, repos, path):
        """Generator yielding (name, tooltip, url) tuples for links of interest
        in relation with the currently browsed path."""

Great idea, I'd be nice if this will be in 0.10 at least. The more interfaces Trac'll have then it'll be more flexible :-).

[Christian Boos]

Hm, no, no more stuff in 0.10 at this point :(, as we're close to release it

But hey, 0.11 development will start soon and will be even more fun ;)

[Radek Bartoň]

Closing as fixed, because request handling implemented and source browser link will wait till 0.11 interface.