Link API docs with CS ones

[res]

Doxygen offers means to link to external documentation (see http://www.stack.nl/~dimitri/doxygen/external.html). Utilize these to link to the CS docs.

[genjix]

done.

[res]

Replying to genjix:

done.

It does not work: links to the CS docs look like href="$CRYSTAL/out/docs/html/api/classcsColor.html".

Also, consider the level of automation with which the CS and CEL docs are created:

• CS docs are generated nightly by the jobber; this should also probably generate a .tag file.
• The crystalspace.tag file is quite big and only really used by the jobber and when generating docs. So it may be better to find some way to leave the .tag file out of SVN.

[genjix]

Did you read the history.txt entry?

	  To set the link do:
	    ./docs/doxygen/installdox -l crystalspace.tag@$CS/out/docs/html/api docs/html/api/*

You need to run that before the links are corrected. I tried to link to the online ones but they had .php extension which is problematic to say the least.

As for autogenerating the tag file... I was going to add GENERATE_TAG to cs, but I wasn't sure if cel should really interfere with cs. If its no problem then thats ok.

[genjix]

btw, cs docs can be fully embedded in cel docs, but then thats an entire copy of cs api (which is huge) in cel api.

[res]

Replying to genjix:

Did you read the history.txt entry? {{{ To set the link do: ./docs/doxygen/installdox -l crystalspace.tag@$CS/out/docs/html/api docs/html/api/* }}} You need to run that before the links are corrected. I tried to link to the online ones but they had .php extension which is problematic to say the least.

I did not run it; I looked at the docs as checked out from the SVN repository. They were checked in with wrong hrefs.

As for autogenerating the tag file... I was going to add GENERATE_TAG to cs, but I wasn't sure if cel should really interfere with cs. If its no problem then thats ok.

The same argumentation as for a crystalspace.tag in CEL applies here: the .tag file is relatively large while only of limited use for most users. So it'd probably be best if the .tag file is generated by the jobber for the purpose or documentation, but not checked into SVN or similar.

[res]

Replying to genjix:

btw, cs docs can be fully embedded in cel docs, but then thats an entire copy of cs api (which is huge) in cel api.

Well the CS API docs were ditched from the CS SVN itself due their volume and the SVN issues they causes... so it's probably not a good idea to start including them in CEL.

[eric]

Replying to res:

The same argumentation as for a crystalspace.tag in CEL applies here: the .tag file is relatively large while only of limited use for most users. So it'd probably be best if the .tag file is generated by the jobber for the purpose or documentation, but not checked into SVN or similar.

I agree with Frank's assessment. The jam API documentation generation action(s) can be updated to allow production of a tag file if desired. The tag file does not especially belong in SVN. It may be useful for jam install to install the tag file somewhere in case some other, external project would like to link to the installed CS documentation.

For CEL, when documentation is built by a person at a console, the API documentation generation target could take advantage of the CS tag file either in the CS build directory or at the installed CS location.

On ther other hand, for the case of published CEL API documentation, CEL jobber would be responsible for obtaining somehow a copy of a recently-generated CS tag file. jobber is also an appropriate mechanism for post-processing its copy of the CS tag file in order to account for .php extensions and any other similar issues.

Having CEL jobber obtain a copy of a recently-generated CS tag file is somewhat sticky since it implies some sort of communication between CS jobber and CEL jobber. One possibility is to upload the CS tag file to the online CS API documentation directory along with all the other HTML/PHP/CSS files. CEL jobber could then grab the tag file from that location. The benefit of this approach is that CEL jobber would then have a guarantee that the CS tag file it is employing is as recent as the published documentation which it references.

An alternative, though less robust, approach would be to have CEL jobber generate its own copy of the CS tag file. CEL jobber already grabs a local copy of CS/include from SVN, so it is conceivable that it also could grab a copy of CS/docs/doxygen, and possibly fake up a jam target locally to genererate the CS tag file.

[res]

Replying to eric:

Having CEL jobber obtain a copy of a recently-generated CS tag file is somewhat sticky since it implies some sort of communication between CS jobber and CEL jobber. One possibility is to upload the CS tag file to the online CS API documentation directory along with all the other HTML/PHP/CSS files. CEL jobber could then grab the tag file from that location. The benefit of this approach is that CEL jobber would then have a guarantee that the CS tag file it is employing is as recent as the published documentation which it references.

This seems reasonably simple. Since the jobber is run on the same server that serves the web page, "uploading" or "downloading" the .tag file would be little more than using the correct path in the file system (at least in the context of the normal CEL jobber).

Actually, for CS, we could probably always enable the tag file generation. The API docs are not in the SVN any more anyway, so the (IIRC) previously existing concern that always generating it would let it end up in the source repository and inconvenience users dropped away.