Dokumentieren von CMake-Skripten

Question

Ich finde mich in einer Situation, in der ich eine Reihe von benutzerdefinierten CMake-Makros und Funktionen genau dokumentieren möchte und fragte mich, wie es geht.

Das erste, was einfach in den Sinn kommt, ist die eingebauten Syntax und nur Dokument-Skripte verwenden, etwa so:

# ----------------------------- 
# [FUNCTION_NAME | MACRO_NAME] 
# ----------------------------- 
# ... description ... 
# ----------------------------- 

Das ist in Ordnung. Allerdings möchte ich allgemeine doc Generatoren, zum Beispiel Doxygen, verwenden, um auch externe Dokumentation zu generieren, die von jedem ohne mit Blick auf die Implementierung gelesen werden kann (was ein häufiges Szenario ist).

Ein Weg wäre, einen einfachen Parser zu schreiben, der direkt aus dem CMake-Skript einen entsprechenden C/C++ - Header mit den entsprechenden Signaturen und Dokumentationen erzeugt, der von doxygen oder vergleichbaren Werkzeugen verarbeitet werden könnte. Man könnte einen solchen Header auch manuell pflegen - was offensichtlich mühsam und fehleranfällig ist.

Gibt es eine andere Möglichkeit, einen Dokumentationsgenerator mit CMake-Skripten zu verwenden?

Answer 1

Hier ist die nächste, die ich bekommen konnte. Folgendes wurde mit CMake 2.8.10 getestet. Momentan wird CMake 3.0 entwickelt, welches ein neues Dokumentationssystem basierend auf Sphinx und reStructuredText bekommen wird. Ich schätze, dass dies neue Wege zur Dokumentation Ihrer Module bringen wird.

CMake 2.8 kann Dokumentation von Ihren Modulen extrahieren, aber nur Dokumentation am Anfang der Datei wird berücksichtigt. Die gesamte Dokumentation wird als CMake-Kommentare hinzugefügt, beginnend mit einer einzelnen #. Double ## wird ignoriert (damit Sie Ihrer Dokumentation Kommentare hinzufügen können). Das Ende der Dokumentation ist durch die erste Nicht-Kommentar-Zeile (z. B. eine Leerzeile) markiert.

Die erste Zeile enthält eine kurze Beschreibung des Moduls. Er muss mit - beginnen und mit einer Periode . oder einer Leerzeile enden.

# - My first documented CMake module. 
# description 

oder # - Meine erste dokumentierte CMake Modul # # Beschreibung

In HTML Ausgangsleitungen mit an zwei oder mehr Räumen (nach dem #) mit nichtproportionalen Schriftart formatiert.

Beispiel:

# - My custom macros to do foo 
# 
# This module provides the macro foo(). 
# These macros serve to demonstrate the documentation capabilietes of CMake. 
#  
# FOO([FILENAME <file>] 
#   [APPEND] 
#   [VAR <variable_name>] 
# ) 
# 
# The FOO() macro can be used to do foo or bar. If FILENAME is given, 
# it even writes baz. 

MACRO(FOO) 
... 
ENDMACRO() 

Um nur Dokumentation für die benutzerdefinierte Module zu erzeugen, rufen

cmake -DCMAKE_MODULE_PATH:STRING=. --help-custom-modules test.html 

Einstellung CMAKE_MODULE_PATH Sie zusätzliche Verzeichnisse für Module zur Suche definieren. Andernfalls müssen sich Ihre Module im CMake-Standardspeicherort befinden. --help-custom-modules begrenzt die Dokumentationsgenerierung auf benutzerdefinierte Nicht-CMake-Standardmodule. Wenn Sie einen Dateinamen angeben, wird die Dokumentation in die Datei geschrieben, andernfalls als Standard. Wenn der Dateiname eine erkannte Erweiterung hat, wird die Dokumentation entsprechend formatiert.

Folgende Formate sind möglich:

• .html für HTML-Dokumentation
• .1-.9 für Manpage
• .docbook für Docbook
• etwas anderes: Klartext