[Differential] [Request, 598 lines] D2854: New: ECMGenerateApiDox, for generating qch & tag files

[kossebau (Friedrich W. H. Kossebau)]

kossebau created this revision.
kossebau added subscribers: Frameworks, KDevelop, ochurlaud.

REVISION SUMMARY
  To enable creation of qch files during a normal build, 
  for documenting the public API of a lib.
  These macros are especially done with release builds in mind,
  so distributed packages (like from Linux distributions) can
  include qch files matching the version of the library and will be
  also automatically updated on new versions of the libary.
  
  Next to that the macros also supports linking between different
  qch files, so a subclass from another library for which there also
  is a qch file installed will be linked to the entry in that other
  qch file.
  
  This should be a nice addition to the online service like api.kde.org,
  like qassitent/qt qhc files are to doc.qt.io
  
  Open questions:
  a) recommended install path for qch and tag files?
  What would KDevelop & Co. like for easy automatic discovery of qch files?
  What would be a nice var name for such dirs to be used with KDEInstallDirs?
  
  b) best way to specify sources to use for created API docs?
  SOURCE_DIRS in this draft is the only option to specify the input to
  doxygen, following the inspiration of kde-dev-scripts/kdedoxyqt.sh.
  Being part of the buildsystem and having access to more data like sources
  for a library target or even special target metadata, supporting other variants
  might be nice to have. Looking for proposals from experienced target
  metadata users here.
  
  c) sharing metadata with kapidox
  Initially I placed these macros into the kapidox module, as this seems the
  logic place. And would match what kdoctools does for user manuals.
  Just, that would create a build dependency on kapidox which complicates usage
  a little. Having these macros in ECM delivers them with no extra effort
  needed.
  The data in metainfo.yaml is partially duplicated with the data feed into
  the macros. How to deduplicate that is still open. Especially with the need
  to not depend on external data sources like identify.kde.org.
  
  d) naming pattern for cmake config variables for qch & tag files sane?
  
  Issues:
  
  - doxygen for me currently creates broken inter-qch links.
  - KDevelop for some created qch does not show the content (but assistant
  
  does).
  
  - html style in assistant sometimes covers class names

BRANCH
  addGenerateApiDox

REVISION DETAIL
  https://phabricator.kde.org/D2854

AFFECTED FILES
  modules/ECMDoxygenQCH.config.in
  modules/ECMGenerateApiDox.cmake

EMAIL PREFERENCES
  https://phabricator.kde.org/settings/panel/emailpreferences/

To: kossebau
Cc: ochurlaud, #kdevelop, #frameworks
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.kde.org/pipermail/kde-frameworks-devel/attachments/20160925/d6ed3e9f/attachment-0001.html>