Review Request 119740: Display the metadata of Frameworks in the API documentation menu

[Denis Steckelmacher]

-----------------------------------------------------------
This is an automatically generated e-mail. To reply, visit:
https://git.reviewboard.kde.org/r/119740/
-----------------------------------------------------------

(Updated Aug. 12, 2014, 8:35 p.m.)


Status
------

This change has been marked as submitted.


Review request for KDE Frameworks.


Repository: kapidox


Description
-------

The README.md file of each framework repeats information like the mailing list or the git repository of the framework. This patch extends kapidox so that this information is extracted automatically from the metadata.yaml file and displayed in the menu bar of the apidox website. The information is displayed there because the menu is built using Jinja templates (easy to change and powerful) and because this place is always visible.

Here is the information shown:

* A link to inqlude
* Maintainer (if the "maintainer" key of metadata.yaml does not contain an at symbol, then "@kde.org" is appended). A module having no maintainer is said to be maintained by "The KDE Community"
* Basic dependencies. The idea is to highlight the fact that Tier 1 frameworks depend only on Qt (and possibly other non-framework libraries). A list of real dependencies is not yet available but there are tools for that that may one day become available.
* Supported platforms
* Community links (mailing list, IRC channel and projects.kde.org page)
* Code snippet showing how to use the framework with CMake
* Code snippet showing how to use the framework with QMake (so that Qt-only users feel at home)
* A "git clone" snippet


Diffs
-----

  src/kapidox/data/templates/fwinfo.html PRE-CREATION 
  src/kapidox/generator.py 203586e 
  src/kgenframeworksapidox fbc03c1 
  src/kapidox/data/htmlresource/kde.css 0ecdf57 
  src/kapidox/data/templates/doxygen.html b7463c0 

Diff: https://git.reviewboard.kde.org/r/119740/diff/


Testing
-------

I've built the documentation of all the frameworks and the code runs. The information is correct in all case except the CMake and QMake library names of some frameworks. This comes from the fact that this information is not directly available in metadata.yaml and needs to be guessed. Problems arise when a framework does not follow the ususual K<name> or <name> naming scheme (for instance, KArchive is KF5::Archive, but KDED is not KF5::DED). This can be solved by adding a key in metadata.yaml:

cmakename: KDED

Some changes are also needed when a framework installs several libraries (SonnetCore and SonnetUi for instance). This can be fixed using this key:

libraries: [SonnetCore, SonnetUi]

There may still be names that are not correct. Ideally, there should not be any guessing at all and all the metadata.yaml should provide a CMake configuration name, a list of CMake libraries and a list of QMake libraries. This information can be found in the CMakeLists.txt file and I'm okay with updating the metadata.yaml file of all the frameworks if you want.


Thanks,

Denis Steckelmacher

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.kde.org/pipermail/kde-frameworks-devel/attachments/20140812/2d82fc8f/attachment.html>