Re: [Doxygen-users] Best way to 'relocate' links to html

[Edward M. <Edw...@ce...>]

On 17 Feb 2014, at 21:17, Dimitri van Heesch <do...@gm...<mailto:do...@gm...>> wrote:

Hi Edward,

On 17 Feb 2014, at 16:32 , Edward Moyse <edw...@ce...<mailto:edw...@ce...>> wrote:

Hi all,

I'm just trying to understand why our doxygen builds take such an insane amount of time. I think we're not currently building tags first then making the html after, as recommended here:
http://stackoverflow.com/questions/8247189/doxygen-is-slow/8247993#8247993
and so I'm investigating changing this...

But also we seem to have an incredibly slow part of the process where the html is parsed to turn links like:
file:///my/local/path/doc/xAODMuon/html/classSG_1_1AuxElement.html

into
html://a/web/location/doc/xAODMuon/html/classSG_1_1AuxElement.html

(The reason for this is we build the documentation on a local machine, then once it's done it's copied to a web visible location)

Presumably there is a better way to do this? I'd have thought it should be possible to specify that the html will eventually live elsewhere, but I had a look at the documentation and couldn't see it?

Doxygen normally doesn't create any absolute URLs (with file:// or http:// in them), so the URL renaming process is not part of doxygen and shouldn't be needed at all. Just copy the HTML files to the web location in the end.

Hi Dimitri,

Thanks for the reply, and sorry for the delay in getting back to you - I've been trying to investigate a bit more before asking again.

What we have is a structure like the following:

ProjectA
PackageA
build
headers
src
PackageB
build
headers
src
ProjectB
PackageC
build
headers
src
PackageD
build
headers
src

What we try to end up with is:
Output/doc/
PackageA
html
PackageA.tag
PackageB
html
PackageB.tag
PackageC
html
PackageC.tag
PackageD
html
PackageD.tag

I'm trying to work out how best to achieve this...

What I'm trying right now involves two steps (as you suggested):
1) loop through each package (in the original location), build the tagfile of the package and output it to Output/PackageX.tag
2) loop through each package again (again in the original location), and generate the html in Output/PackageX/html

For both step1 and step2 the generated Doxyfiles (one per package) have:
OUTPUT_DIRECTORY = /Output/doc/PackageX
INLINE_SOURCES         = YES

For step 1, the Doxyfile has :
GENERATE_HTML = NO
TAGFILES =
GENERATE_TAGFILE = /Output/doc/PackageX.tag

For step 2, the Doxyfile has:
GENERATE_HTML = YES
TAGFILES = /Output/doc/PackageA.tag=/Output/doc/PackageA/html
i.e. paths are absolute (since the relative path isn't reliable - the build location can change).

There are quite a few problems unfortunately.

1) INLINE_SOURCES seems to be ignored... (which is just ver
2) Many links don't work.

For example, PackageA has MyObjectA which uses MyObjectB from PackageB, and both exist in the namespace Foo.

In the generated documentation for MyObjectA, there is a link to MyObjectB, but in fact it points to

When I look into PackageB.tag, I see the following:
  <compound kind="file">
    <name> MyObjectB </name>
    <path>/ProjectA/PackageA/headers/</path>
    <filename> MyObjectB_8h</filename>
    <includes id="MyObjectB_8h" name="MyObjectB.h" local="yes" imported="no">versions/MyObjectB.h</includes>
    <namespace>Foo</namespace>
    <member kind="typedef">
      <type> MyObjectB_v1</type>
      <name> MyObjectB </name>
      <anchorfile>namespaceFoo.html</anchorfile>
      <anchor>a795ac8d2e30fdc75f7c9266766629005</anchor>
      <arglist></arglist>
    </member>
  </compound>

i.e. the anchorfile is somehow being misunderstood to be the namespace file. And the <path> tag points to the complete build directory (I'm not sure if this is a problem or not?). The problem here might be related to the fact that we make quite a lot of use of typedefs in these particular packages... In fact, I just tried changing some of the documentation to refer to ObjectB_v1 rather than ObjectB, and it worked correctly. But this is a bit of a pain, since we want to hide the version from users, and we don't want to have to update all the documentation once the version changes.

A related question - is there any way to tell Doxygen that, never mind how many packages you find namespace Foo in, THIS is the definitive documentation and to only use this? We have Foo spread across hundreds of packages, unfortunately.

Thanks in advance for any debugging tips you could give (I hope the above is comprehensible - I'm having to obfuscate our code, which makes this a lot more painful to explain!)

Cheers,

Ed