Integrating kf5dot and kapidox

[Aurélien Gâteau]

[Errr... my message got truncated. Let's try again]

Now that kf5dot is (hopefully) mostly feature-complete, I think it is
time to decide how to integrate it in kapidox.

The way kf5dot works is the following:

1. kf5dot-prepare runs CMake on the frameworks source to generate
   Graphviz dot files. It also copies the framework yaml file in the
   output dir.

2. kf5dot-generate parses the dot files and the framework yaml file to
   generate new dot files, which can then be passed to the `dot` tool
   to generate png files.

The flow is thus:

~/src/frameworks/
    kauth/
        src/
        kauth.yaml
        CMakeLists.txt
    ...
    kio/
        src/
        kio.yaml
        CMakeLists.txt
    ...

    |
    V

kf5dot-prepare ~/src/frameworks ~/dots

    |
    V

~/dots/
    tier1/
        ...
    tier2/
        kauth/
            kauth.dot
            kauth.yaml
        ...
    tier3/
        kio/
            kio.dot
            kio.yaml
    ...
    |
    V

kf5dot-generate ~/dots/tier*/*/*.dot --framework kauth \
    | dot -Tpng > ~/out/kauth.png

kf5dot-generate ~/dots/tier*/*/*.dot --framework kio \
    | dot -Tpng > ~/out/kio.png

kf5dot-generate ~/dots/tier*/*/*.dot \
    | tred | dot -Tpng > ~/out/kf5.png

    |
    V

~/out/
    kauth.png
    kio.png
    kf5.png


# Integration

First, the code. Right now the kf5dot code is in its own repository, I
think it should be moved to kapidox/src/kf5dot, unless someone thinks
it's a bad idea.

Second, api.kde.org deployment. kf5dot-prepare needs to be able to run
CMake on the source code. @Allen: is it possible to do this on
api.kde.org?

Third: inclusion in the generated documentation. I would like to see the
dependency diagram of each framework included in the landing page of its
documentation, and possible the overall KF5 diagram (if we think it is
useful) on the main landing page.

Generating dependency diagrams should not be required however: we should
ensure kgenapidox can be run by developers and framework maintainers on
their local machines, since it reduces the effort needed to maintain
documentation (and it helps preventing any "works only on the production
system" issue).

This means kgenapidox and kgenframeworksapidox should be able to take
advantage of the dependency diagrams if they are available, but should
not fail if they are not.

I think this can be done by adding a --dependency-diagram-dir option to
the scripts, which would point to the dir where all the diagrams are.
kgenapidox should then include the diagram in the HTML page generated
from the README.md of each framework.
Does it make sense to you?

@Alex: is it possible to have a Pystache template for the README.md?

Aurélien