Δημιουργώντας το δικό σας έργο
Οι επόμενες ενότητες περιγράφουν τα βήματα που απαιτούνται για να ενσωματώσετε το GTK-Doc στο έργο σας. Αυτές οι ενότητες προϋποθέτουν ότι εργάζεσθε σε ένα έργο που λέγεται 'meep'. Το έργο περιέχει τη βιβλιοθήκη 'libmeep' και την εφαρμογή 'meeper' για τον τελικό χρήστη. Θεωρούμε επίσης, ότι θα χρησιμοποιείτε το autoconf και το automake. Επιπλέον, η ενότητα αρχεία makefiles ή άλλα συστήματα ανάπτυξης θα περιγράψει τα βασικά στοιχεία που απαιτούνται για να εργαστείτε σε μια διαφορετική δόμηση ρυθμίσεων.

Δημιουργία του σκελετού τεκμηρίωσης
Εντός του ριζικού καταλόγου του έργου δημιουργήστε το φάκελο docs/reference (ώστε να μπορείτε να χρησιμοποιήσετε το όνομα docs/help για την τεκμηρίωση του τελικού χρήστη). Συνιστάται να δημιουργήσετε έναν ακόμη υποκατάλογο με το όνομα του πακέτου τεκμηρίωσης. Αυτό δε χρειάζεται για πακέτα που περιλαμβάνουν μόνο μία βιβλιοθήκη.
Αυτό θα φαίνεται, λοιπόν, όπως εμφανίζεται παρακάτω:

Παράδειγμα δομής καταλόγου

meep/
  docs/
    reference/
      libmeep/
      meeper/
  src/
    libmeep/
    meeper/

Ενσωμάτωση στο autoconf
Πολύ εύκολα! Απλά προσθέτετε μία γραμμή στη δέσμη ενεργειών configure.ac.

Ενσωμάτωση στο autoconf

# έλεγχος για gtk-doc
GTK_DOC_CHECK([1.14],[--flavour no-tmpl])

Αυτό απαιτεί από όλους τους προγραμματιστές να έχουν εγκατεστημένο το gtk-doc. Αν είναι εντάξει για το έργο σας να έχετε μια επιπλέον δόμηση ρυθμίσεων για το api-doc, μπορείτε να το επιλύσετε όπως αναφέρεται παρακάτω. Αφήστε το ως έχει, όσο το gtkdocize αναζητά την αρχή της σειράς για το GTK_DOC_CHECK.

Προαιρετικά διατηρήστε το gtk-doc

# έλεγχος για gtk-doc
m4_ifdef([GTK_DOC_CHECK], [
GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
],[
AM_CONDITIONAL([ENABLE_GTK_DOC], false)
])

Το πρώτο όρισμα χρησιμοποιείται για έλεγχο του gtkdocversion κατά τη ρύθμιση. Το δεύτερο, προαιρετικό όρισμα χρησιμοποιείται από το gtkdocize. Η μακροεντολή GTK_DOC_CHECK επίσης προσθέτει αρκετούς διακόπτες ρύθμισης:
--with-html-dir= PATH : διαδρομή προς την εγκατεστημένη τεκμηρίωση
--enable-gtk-doc : χρήση gtk-doc για τη δόμηση τεκμηρίωσης [προεπιλογή=no]
--enable-gtk-doc-html : δόμηση τεκμηρίωσης σε μορφή html [προεπιλογή=yes]
--enable-gtk-doc-pdf : δόμηση τεκμηρίωσης σε μορφή pdf [προεπιλογή=no]
Το GTK-Doc είναι απενεργοποιημένο από προεπιλογή! Να θυμάστε να χρησιμοποιείτε την επιλογή '--enable-gtk-doc' στην επόμενη εκτέλεση του configure. Διαφορετικά, εγκαθίσταται η προπαραχθείσα τεκμηρίωση (δυνατότητα χρήσιμη για τον χρήστη, αλλά όχι για τον προγραμματιστή).
Furthermore it is recommended that you have the following line inside your configure.ac script. This allows gtkdocize to automatically copy the macro definition for GTK_DOC_CHECK to your project.

Προετοιμασία για το gtkdocize

AC_CONFIG_MACRO_DIR(m4)

Όταν όλες οι αλλαγές στο configure.ac έχουν γίνει, ενημερώστε το αρχείο configure. Αυτό μπορείτε να το κάνετε επανεκετελώντας το autoreconf -i ή το autogen.sh.

Ενσωμάτωση στο automake
Πρώτα αντιγράψτε το Makefile.am από τον υποκατάλογο με τα παραδείγματα των gtkdoc-sources στον κατάλογο της τεκμηρίωσης API του έργου σας ( ./docs/reference/<package>). Ένα τοπικό αντίγραφο θα πρέπει να είναι διαθέσιμο π.χ. στο /usr/share/doc/gtk-doc-tools/examples/Makefile.am. Αν έχετε πολλά doc-packages επαναλάβετε αυτό το βήμα για το καθένα απο αυτά.
Το επόμενο βήμα είναι να τροποποιήσετε τις ρυθμίσεις στο Makefile.am. Πριν από κάθε ρύθμιση υπάρχει ένα σχόλιο που εξηγεί τη χρησιμότητά της. Οι περισσότερες είναι σημαίες που στέλνονται στα αντίστοιχα εργαλεία. Κάθε εργαλείο διαθέτει μια μεταβλητή της μορφής <TOOLNAME>_OPTIONS. Όλα τα εργαλεία υποστηρίζουν την επιλογή --help για την παραγωγή λίστας με τις υποστηριζόμενες παραμέτρους.

Ενσωμάτωση στο autogen
Τα περισσότερα έργα διαθέτουν ένα σενάριο autogen.sh για τη δόμηση υποδομών μετά από έναν έλεγχο από το σύστημα ελέγχου εκδόσεων (π.χ., cvs/svn/git). Το GTK-Doc διαθέτει το εργαλείο gtkdocize, το οποίο μπορεί να χρησιμοποιηθεί για ένα τέτοιο σενάριο. Θα πρέπει να εκτελείται πριν το autoheader, το automake ή το autoconf.

Εκτέλεση του gtkdocize από το autogen.sh

gtkdocize || exit 1

Κατά την εκτέλεσή του, το gtkdocize αντιγράφει το gtk-doc.make στο ριζικό κατάλογο του έργου σας (ή στον κατάλογο που ορίζει η επιλογή --docdir). Επίσης, ελέγχει τη δέσμη ενεργειών configure για να βρει την κλήση στο GTK_DOC_CHECK.
Αρχικά, το GTK-Doc δημιουργούσε αρχεία προτύπων εκεί που οι προγραμματιστές εισήγαγαν την τεκμηρίωση. Δυστυχώς, αυτή η προσέγγιση δεν ήταν ιδιαίτερα επιτυχής (π.χ η ανάγκη για παραγωγή αρχείων στο σύστημα ελέγχου εκδόσεων). Από την έκδοση 1.9 και μετά, τα πρότυπα αρχεία δεν είναι πλέον απαραίτητα. Σας συνιστούμε να διατηρείτε την τεκμηρίωση στον κώδικα. To gtkdocize υποστηρίζει πλέον την επιλογή --flavour no-tmpl που επιλέγει ένα αρχείο makefile που δεν χρησιμοποιεί καθόλου πρότυπα tmpl. Πέρα από την άμεση προσθήκη της επιλογής στην κλήση της εντολής, μπορεί να προστεθεί και σε μια μεταβλητή περιβάλλοντος που ονομάζεται GTKDOCIZE_FLAGS ή να ορισθεί ως δεύτερη παράμετρος στη μακροεντολή GTK_DOC_CHECK στο σενάριο configure. Αν δεν έχετε κάνει ποτέ αλλαγές με το χέρι σε αρχεία προτύπων και μεταβαίνετε από μια παλιότερη έκδοση του gtkdoc, παρακαλώ αφαιρέστε τον κατάλογο (π.χ. από το σύστημα ελέγχου εκδόσεων).

Εκτέλεση της δόμησης τεκμηρίωσης
Αφού ολοκληρωθούν τα προηγούμενα βήματα, προχωρήστε στην δόμηση. Πρώτα, θα πρέπει να εκτελεσθεί εκ νέου το autogen.sh. Αν το σενάριο εκτελεί και το configure, προσθέστε την επιλογή --enable-gtk-doc. Διαφορετικά, εκτελέστε εσείς τοconfigure με αυτή την επιλογή.
Η πρώτη εκτέλεση του make δημιουργεί μια σειρά από πρόσθετα αρχεία στους καταλόγους της τεκμηρίωσης. Τα σημαντικά είναι τα: <package>.types, <package>-docs.xml (στο παρελθόν .sgml), <package>-sections.txt.

Εκτέλεση της δόμησης τεκμηρίωσης

./autogen.sh --enable-gtk-doc
make

Τώρα, μπορείτε να εμφανίσετε το docs/reference/<package>/index.html στον περιηγητή σας. Είναι αλήθεια ότι προς το παρόν το αποτέλεσμα είναι μάλλον απογοητευτικό. Μην ανησυχείτε όμως. Στο επόμενο κεφάλαιο θα μάθετε πώς μπορείτε να ζωντανέψετε τις σελίδες σας.

Ενσωμάτωση σε συστήματα ελέγχου εκδόσεων
Ο εμπειρικός κανόνας είναι ότι αυτά τα αρχεία που επεξεργασθήκατε πρέπει να περάσουν από τον έλεγχο έκδοσης. Για τυπικά έργα, πρόκειται για τα αρχεία: <package>.types, <package>-docs.xml (στο παρελθόν .sgml), <package>-sections.txt, Makefile.am.
Αρχεία στους καταλόγους xml/ και html/ δεν θα πρέπει να υποβληθούν σε έλεγχο έκδοσης. Ούτε και αρχεία xml/ and html/.

Ενσωμάτωση στα αρχεία makefiles ή άλλα συστήματα δόμησης
Στην περίπτωση που κάποιος δε θέλει να χρησιμοποιήσει το automake και, επομένως, το gtk-doc.mak θα χρειαστεί να καλέσει τα εργαλεία του gtkdoc στη σωστή σειρά στα makefiles (ή άλλα εργαλεία δόμησης).

Βήματα δόμησης τεκμηρίωσης

DOC_MODULE=meep
// sources have changed
gtkdoc-scan --module=$(DOC_MODULE) --source-dir=...
gtkdoc-scangobj --module=$(DOC_MODULE)
gtkdoc-mkdb --module=$(DOC_MODULE) --output-format=xml
// xml files have changed
mkdir html
cd html && gtkdoc-mkhtml $(DOC_MODULE) ../meep-docs.xml
gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html

Πρέπει να κοιτάξετε στα αρχεία Makefile.am και gtk-doc.mak για να επιλέξετε τις ρυθμίσεις που χρειάζονται.

Ενσωμάτωση με συστήματα δόμησης CMake
Το GTK-Doc παρέχει το άρθρωμα GtkDocConfig.cmake (και το αντίστοιχο άρθρωμα GtkDocConfigVersion.cmake). Επίσης παρέχει την εντολή gtk_doc_add_module την οποία μπορείτε να ορίσετε στο αρχείο CMakeLists.txt.
Το ακόλουθο παράδειγμα δείχνει πως να χρησιμοποιήσετε την εντολή.

Παράδειγμα χρήσης του GTK-Doc από το CMake

find_package(GtkDoc 1.25 REQUIRED)

# Create the doc-libmeep target.
gtk_doc_add_module(
   libmeep ${CMAKE_SOURCE_DIR}/libmeep
      XML meep-docs.xml
      LIBRARIES libmeep
)

# Build doc-libmeep as part of the default target. Without this, you would
# have to explicitly run something like `make doc-libmeep` to build the docs.
add_custom_target(documentation ALL DEPENDS doc-libmeep)

# Install the docs. (This assumes you're using the GNUInstallDirs CMake module
# to set the CMAKE_INSTALL_DOCDIR variable correctly).
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/libmeep/html
        DESTINATION ${CMAKE_INSTALL_DOCDIR})