Planeshift API

[Ralleyon]

In case you didn't know, this can be generated with the help of psdoxyconf file from the docs directory in the cvs. Basically it provides a tree of the planeshift code, easy to read & navigate. In the following I will post a coversation with Bereror (Enar) who provided his additions/tweaks to the psdoxyconf file and helped me generate one for myself. Thanks Enar!

If you're on linux, just use your favorite package manager and install the doxygen package and its dependencies (if any.)

And...

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

I'd like to generate the API documentation with doxygen like you did but I can't seem to "tune" it correctly. Could you please tell me (if you got the time) in a 1-2-3 sequence what to change and where to run the command so that I get a result like your page?

You modify the psdoxyconf file in the docs directory. There seems to be not too many differences between the one that I used and the one from the CVS repository:

Code: [Select]

119c119
< STRIP_FROM_PATH        =
---
> STRIP_FROM_PATH        = /home/enar/ps/planeshift/
177c177
< TAB_SIZE               = 8
---
> TAB_SIZE               = 4
571c571
< COLS_IN_ALPHA_INDEX    = 5
---
> COLS_IN_ALPHA_INDEX    = 3
578c578
< IGNORE_PREFIX          =
---
> IGNORE_PREFIX          = ps paws
605c605
< HTML_HEADER            = psdoxyheader.html
---
> HTML_HEADER            =
684c684
< GENERATE_TREEVIEW      = NO
---
> GENERATE_TREEVIEW      = YES
1167c1167
< SEARCHENGINE           = NO
---
> SEARCHENGINE           = YES

I guess you know that Doxygen online help is available here.

STRIP_FROM_PATH removes parts of the path from linked source files so that they don't show up in the documentation.

TAB_SIZE, well, sets the tab size

COLS_IN_ALPHA_INDEX specifies the number of columns on the index page. 5 seems to be working better than the original 3.

IGNORE_PREFIX ignores ps and paws when adding classes to the index. This way psItem is shown under "I" and not "P". It probably makes sense to add "gem" and "gui" to that list of prefixes too.

HTML_HEADER specifies an HTML file for the header. I removed the header completely.

GENERATE_TREE_VIEW generates the tree view on the left side.

SEARCHENGINE adds the search box (warning, it will consume quite a lot of CPU time on the server if you have many people using it).


To run the doxygen command, just go to the docs directory and run

Code: [Select]

doxygen psdoxyconf
I hope this helps.

Regards,
Enar (Bereror)

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

[Caarrie]

since doxygen has changed a bit since this was posted i have updated the filie used to generate the content, it can be found at
http://www.yliakum.com/psdocs/index.php?page=5

this file is also no longer is the ps repro, you will have to add it yourself.

[Lanarel]

For windows, get doxygen here.
Save the file from Caarries post in the doxygen directory in the svn tree (no need to change anything in that case). Run the doxywizard, click load and open the saved file. Then just press start and wait a (long) while.
Then open the index.html file that is saved somewhere

Also, get graphviz here. It is a tool for making diagrams, and includes dot, which can be used by doxygen to make nice graphs of class diagrams, relations between files, etc. It often makes things much clearer, or in the least makes everything look impressively complicated

Download from the download link on the page linked above, agree to the license stuff, download and install the windows install. Now in doxywizard load the doxygen file you saved from Caarries example. Now click the expert button. It has a lot of tabs with all the settings specified in the file you loaded. Click on the small black arrow on the right to get to the tab nearly at the end, marked 'dot' and select it. In the DOT_PATH field, enter the bin directory of the graphviz install (somewhere/Graphviz/bin).
You can enable a few more graphs. I like the call and caller graphs, because they look really complicated Beware, these may take a while to create.
Now click OK. Press the SAVE button and save the file again (overwrite old or make new).
Press start. Drink a cup of coffee, and another one (depending on how many graphs you wanted).
WHen finished, in the subdirectory html there should be many many files. In the middle somewhere there is index.html. I suggest to make a shortcut to that file (a directory higher for example) for refinding it more easily.
Open it, and start clicking on random links

Here is a small example. For more complicated ones, look for the 230 classes derived from some event, or the hundreds of interrelated classes starting from messagecracker :

[tsharky87]

Why not just have this API available to download instead of going through all that hassle? I managed to make a copy, so I'd be perfectly willing to supply mine, if it is needed. Overall I'd say this project could use a lot better documentation...

[Vornne]

Because the API might change any time a developer commits

There was a dev that hosted docs on his site a while back, but I don't think they are kept up to date.

[Xordan]

Why not just have this API available to download instead of going through all that hassle? I managed to make a copy, so I'd be perfectly willing to supply mine, if it is needed. Overall I'd say this project could use a lot better documentation...

Yeah, we need to generate this stuff nightly and have it in an easily findable location.

[Bereror]

There was a dev that hosted docs on his site a while back, but I don't think they are kept up to date.

If you mean http://www.vaikene.net/planeshift/api/, then this should be now updated every night at 3 am GMT if my cron job works properly.