Automatically generate user documentation

.gitignore

@@ -1,5 +1 @@
 *~
-doc/doxygen
-doc/index.html
-doc/install.html
-doc/quickStart.html

CMakeLists.txt

@@ -99,12 +99,27 @@ add_executable (clang-tags-server
 target_link_libraries (clang-tags-server ${LIBS})
 
 
-configure_file (
-  "${PROJECT_SOURCE_DIR}/env.sh.in"
-  "${PROJECT_BINARY_DIR}/env.sh")
-configure_file (
-  "${PROJECT_SOURCE_DIR}/env.el.in"
-  "${PROJECT_BINARY_DIR}/env.el")
+function (ct_template path)
+  configure_file (
+    "${PROJECT_SOURCE_DIR}/${path}"
+    "${PROJECT_BINARY_DIR}/${path}")
+endfunction (ct_template)
+ct_template ("env.sh")
+ct_template ("env.el")
+
+# Generate documentation
+ct_template ("Doxyfile")
+ct_template ("doc/export-org")
+ct_template ("doc/generate.el")
+ct_template ("doc/setup.org")
+ct_template ("doc/index.org")
+ct_template ("doc/quickStart.org")
+ct_template ("doc/install.org")
+add_custom_target (doc-doxygen COMMAND doxygen)
+add_custom_target (doc-org     COMMAND ./doc/export-org)
+add_custom_target (doc DEPENDS doc-doxygen doc-org)
+
+
 
 install (
   PROGRAMS     clang-tags
@@ -140,6 +155,10 @@ endfunction (ct_add_test)
 
 enable_testing()
 
+ct_add_test (ct-help
+  "ct-help"
+)
+
 ct_add_test (setup
   "rm -rf src build"
   "cp -R ${PROJECT_SOURCE_DIR}/tests/src ."

Doxyfile

@@ -51,7 +51,7 @@ PROJECT_LOGO           =
 # If a relative path is entered, it will be relative to the location 
 # where doxygen was started. If left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = doc
+OUTPUT_DIRECTORY       = @PROJECT_BINARY_DIR@/doc
 
 # If the CREATE_SUBDIRS tag is set to YES, then doxygen will create 
 # 4096 sub-directories (in 2 levels) under the output directory of each output 
@@ -609,7 +609,7 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
 
-INPUT                  = .
+INPUT                  = @PROJECT_SOURCE_DIR@
 
 # This tag can be used to specify the character encoding of the source files 
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is 

doc/export-org

@@ -0,0 +1,4 @@
+#!/bin/bash
+
+cd doc
+emacs -Q -l generate.el

doc/doc.el → doc/generate.el

@@ -1,8 +1,20 @@
+
+;; Load environment
+(load-file "@PROJECT_BINARY_DIR@/env.el")
+
+;; Create non-read-only variants of clang-tags modes
 (defmacro create-read-only-derived-mode (mode-name)
   `(define-derived-mode ,(intern (format "%s-rw-mode" mode-name)) ,(intern (format "%s-mode" mode-name))
      ,(format "%s-rw-mode" mode-name)
      ,(format "Like %s-mode, but not read-only" mode-name)
      (setq buffer-read-only nil)))
-
 (create-read-only-derived-mode "grep")
 (create-read-only-derived-mode "ct/find-def")
+
+;; Export org-mode files
+(mapc (lambda (fileName)
+	(find-file fileName)
+        (org-html-export-to-html))
+      '("index.org" "quickStart.org" "install.org"))
+
+(kill-emacs)

doc/index.org

@@ -13,7 +13,7 @@ relies on the [[http://clang.llvm.org][clang]] compiler (via the libclang interf
 
   Let us consider the following C++ code:
 
-  #+include: "../tests/src/main.cxx" src c++ -n -r
+  #+include: "@PROJECT_SOURCE_DIR@/tests/src/main.cxx" src c++ -n -r
 
   A few difficulties can be found in this file, making indexing difficult without the help of a
   full-fledged C++ compiler:
@@ -127,9 +127,7 @@ relies on the [[http://clang.llvm.org][clang]] compiler (via the libclang interf
 
 *** Tracing the standard build process
 
-    #+begin_src sh
-      clang-tags trace -- BUILD COMMAND
-    #+end_src
+    #+include: "@PROJECT_BINARY_DIR@/tests/trace-help.out" src fundamental
 
     For non =CMake=-managed projects, there is no "free" way to build the compilation database. One
     way to get the necessary information consists in inspecting the build process as a black box
@@ -143,17 +141,13 @@ relies on the [[http://clang.llvm.org][clang]] compiler (via the libclang interf
     features to inspect the build process.
 
     Example usage:
-    #+begin_src sh
-      make clean                 # Ensure that the whole project will be rebuilt
-      clang-tags trace -- make   # Generate the compilation database
-    #+end_src
+    #+include: "@PROJECT_SOURCE_DIR@/tests/ct-trace" src sh :lines "3-"
+    #+include: "@PROJECT_BINARY_DIR@/tests/ct-trace.out" src fundamental
 
 
 *** Scanning the sources directory
 
-    #+begin_src sh
-      clang-tags scan SRC_DIR -- CLANG ARGS
-    #+end_src
+    #+include: "@PROJECT_BINARY_DIR@/tests/scan-help.out" src fundamental
 
     For relatively simple projects, it can be sufficient to simply scan the top sources directory to
     find all =*.c= or =*.cxx= files, and additionally provide =clang-tags= with a set of command-line
@@ -163,37 +157,54 @@ relies on the [[http://clang.llvm.org][clang]] compiler (via the libclang interf
     #+begin_src sh
       clang-tags scan ../src -- -I.
     #+end_src
+    # #+include: "@PROJECT_SOURCE_DIR@/tests/ct-scan" src sh :lines "3-"
+    # #+include: "@PROJECT_BINARY_DIR@/tests/ct-scan.out" src fundamental
 
 
 ** Indexing the source files
 
 *** Creating the index
 
-    #+begin_src sh
-      clang-tags index [--emacs-conf SRC_DIR]
-    #+end_src
+    #+include: "@PROJECT_BINARY_DIR@/tests/index-help.out" src fundamental
+
+    This command uses the compilation database to index all source files.
+    # An optional argument =--emacs-conf= allows generating a suitable =.dir-local.el=
+    # emacs configuration file in the sources directory.
+
+    Example usage:
+    #+include: "@PROJECT_SOURCE_DIR@/tests/ct-index" src sh :lines "3-"
+    #+include: "@PROJECT_BINARY_DIR@/tests/ct-index.out" src fundamental
 
-    This command uses the compilation database to index all source files. An
-    optional argument =--emacs-conf= allows generating a suitable =.dir-local.el=
-    emacs configuration file in the sources directory.
 
 *** Updating the index
 
-    #+begin_src sh
-      clang-tags update [--all]
-    #+end_src
+    #+include: "@PROJECT_BINARY_DIR@/tests/update-help.out" src fundamental
 
-    This command updates the index. With the optional =--all= switch, the
-    compilation database is also rebuilt using the same sub-command =trace= or
-    =build= as previously.
+    This command updates the index.
+
+    # Example usage:
+    # #+include: "@PROJECT_SOURCE_DIR@/tests/ct-update" src sh :lines "3-"
+    # #+include: "@PROJECT_BINARY_DIR@/tests/ct-update.out" src fundamental
 
 
 ** Looking for symbols
 
 *** Finding the definition of a symbol
 
+    #+include: "@PROJECT_BINARY_DIR@/tests/find-def-help.out" src fundamental
+
+    Example usage:
+    #+include: "@PROJECT_SOURCE_DIR@/tests/ct-find-def-i" src sh :lines "3-"
+    #+include: "@PROJECT_BINARY_DIR@/tests/ct-find-def-i.out" src ct/find-def-rw
+
+
 *** Looking for all references to a symbol
 
+    #+include: "@PROJECT_BINARY_DIR@/tests/grep-help.out" src fundamental
+
+    Example usage:
+    #+include: "@PROJECT_SOURCE_DIR@/tests/ct-grep" src sh :lines "3-"
+    #+include: "@PROJECT_BINARY_DIR@/tests/ct-grep.out" src grep-rw
 
 
 * Emacs user interface

doc/quickStart.org

@@ -27,29 +27,29 @@
 
    This should be done every time the project configuration changes (list of
    source files, compiler switches, ...):
-   #+include: "../tests/ct-trace" src sh :lines "3-"
-   #+include: "../../build/tests/ct-trace.out" src fundamental
+   #+include: "@PROJECT_SOURCE_DIR@/tests/ct-trace" src sh :lines "3-"
+   #+include: "@PROJECT_BINARY_DIR@/tests/ct-trace.out" src fundamental
 
 ** Load the compilation database
 
    After the compilation database has been generated (at the previous step), it
    should be loaded into the system:
-   #+include: "../tests/ct-load" src sh :lines "3-"
-   #+include: "../../build/tests/ct-load.out" src fundamental
+   #+include: "@PROJECT_SOURCE_DIR@/tests/ct-load" src sh :lines "3-"
+   #+include: "@PROJECT_BINARY_DIR@/tests/ct-load.out" src fundamental
 
 ** Index the source files
 
    The first time =clang-tags= is used for a project, the full sources should
    be indexed:
-   #+include: "../tests/ct-index" src sh :lines "3-"
-   #+include: "../../build/tests/ct-index.out" src fundamental
+   #+include: "@PROJECT_SOURCE_DIR@/tests/ct-index" src sh :lines "3-"
+   #+include: "@PROJECT_BINARY_DIR@/tests/ct-index.out" src fundamental
 
    After source files change, the source index can be updated, which saves some
    time by only reparsing new content:
    #+BEGIN_SRC sh
      clang-tags update
    #+END_SRC
-   #+include: "../../build/tests/ct-index.out" src fundamental
+   #+include: "@PROJECT_BINARY_DIR@/tests/ct-index.out" src fundamental
 
 
 * Try the command-line interface
@@ -62,15 +62,15 @@
 
    Find the definition location of the identifier located in =main.cxx= at offset
    849:
-   #+include: "../tests/ct-find-def-r" src sh :lines "3-"
-   #+include: "../../build/tests/ct-find-def-r.out" src ct/find-def-rw
+   #+include: "@PROJECT_SOURCE_DIR@/tests/ct-find-def-r" src sh :lines "3-"
+   #+include: "@PROJECT_BINARY_DIR@/tests/ct-find-def-r.out" src ct/find-def-rw
 
 ** Find symbol references
 
    Find all uses of the =Cursor::location()= method (identified by its USR, as
    given in the second result of =clang-tags find-def= above):
-   #+include: "../tests/ct-grep" src sh :lines "3-"
-   #+include: "../../build/tests/ct-grep.out" src grep-rw
+   #+include: "@PROJECT_SOURCE_DIR@/tests/ct-grep" src sh :lines "3-"
+   #+include: "@PROJECT_BINARY_DIR@/tests/ct-grep.out" src grep-rw
 
 
 * Try the Emacs interface
@@ -97,7 +97,7 @@
    Go to any symbol in the source file, and press =M-<dot>=.  A list of possible
    definition locations for the symbol should be displayed in a dedicated buffer
    called =*ct/find-def*=:
-   #+include: "../../build/tests/ct-find-def-r.out" src ct/find-def-rw
+   #+include: "@PROJECT_BINARY_DIR@/tests/ct-find-def-r.out" src ct/find-def-rw
 
    This buffer is a type of
    =compilation= buffer, meaning that all usual keys are available, especially:
@@ -109,7 +109,7 @@
    While in the =*ct/find-def*= buffer, press =M-<comma>= to get a list of all
    uses of the symbol identified by the entry at point. The symbol uses should
    be displayed in a dedicated buffer called =*ct/grep*=, looking like this:
-   #+include: "../../build/tests/ct-grep.out" src grep-rw
+   #+include: "@PROJECT_BINARY_DIR@/tests/ct-grep.out" src grep-rw
 
    This buffer displays the same content as if you had grepped your
    source files for the symbol name, and filtered out all false positives
@@ -132,6 +132,7 @@
     Exiting...
   #+END_SRC
 
+
 * Read the user guide
 
   Learn more about clang-tags in the [[file:index.org][user manual]].

tests/ct-help

@@ -0,0 +1,10 @@
+#!/bin/bash -e
+
+clang-tags --help \
+| perl -n \
+    -e '$s=0 unless m/^\s*(\S+)/;' \
+    -e 'print "$1\n" if $s;' \
+    -e '$s=1 if m/^\s+SUBCOMMAND/;' \
+| while read subcommand; do
+    clang-tags $subcommand --help >${subcommand}-help.out
+done