openSUSE/kiwi — pull request #196 by rjschwei (2013-02-07 00:51:14+00:00)
Title: doc generation

Well, your visualization comment the other day got me rolling on this little side project (visualization is missing of course, but maybe you want to tackle that ;) ).

This scrip generates html pages for each module listing all the method names and the documentation for each method as delimited by # ... and # ---.

The script also generates call information and a list of things it cannot resolve, after all only Perl can parse perl and this is only a static tool.

There is also a dependency map generated, however I am not yet doing anything with that data. I'd love to see a DAG for our dependencies, but I could not find good info on how to generate one. I'll keep looking.

Leaves the question of integration:
Should we pre-generate the doc html files and then track them in git or should we let OBS create a kiwi-devel-doc package and generate the docs in OBS only?

If we pre-generate and track the files in git I'd still like to create a kiwi-devel-doc package.

Also we have to come to terms with integration of the script into the Makefile and/or pre-commit hook. If we pre-generate I think we should make certain the doc generator runs every time any of the modules is changed to make certain the doc is up to date.

It's a start.

Thoughts/Comments
Robert