From a00385876fb2aff2cb62c3ecefc59bb7eb6649cd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20F=C3=A9votte?= Date: Tue, 6 Aug 2013 23:24:37 +0200 Subject: [PATCH] Automatically generate user documentation --- .gitignore | 4 --- CMakeLists.txt | 31 ++++++++++++++++---- Doxyfile | 4 +-- doc/export-org | 4 +++ doc/{doc.el => generate.el} | 14 ++++++++- doc/index.org | 57 ++++++++++++++++++++++--------------- doc/quickStart.org | 27 +++++++++--------- env.el.in => env.el | 0 env.sh.in => env.sh | 0 tests/ct-help | 10 +++++++ 10 files changed, 102 insertions(+), 49 deletions(-) create mode 100755 doc/export-org rename doc/{doc.el => generate.el} (56%) rename env.el.in => env.el (100%) rename env.sh.in => env.sh (100%) create mode 100755 tests/ct-help diff --git a/.gitignore b/.gitignore index 0926b96..b25c15b 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1 @@ *~ -doc/doxygen -doc/index.html -doc/install.html -doc/quickStart.html diff --git a/CMakeLists.txt b/CMakeLists.txt index 5b24d79..8e1dd48 100644 --- a/CMakeLists.txt +++ b/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 ." diff --git a/Doxyfile b/Doxyfile index d6c6692..dbe360c 100644 --- a/Doxyfile +++ b/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 diff --git a/doc/export-org b/doc/export-org new file mode 100755 index 0000000..d251c78 --- /dev/null +++ b/doc/export-org @@ -0,0 +1,4 @@ +#!/bin/bash + +cd doc +emacs -Q -l generate.el \ No newline at end of file diff --git a/doc/doc.el b/doc/generate.el similarity index 56% rename from doc/doc.el rename to doc/generate.el index 688c79d..28fd5b7 100644 --- a/doc/doc.el +++ b/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) \ No newline at end of file diff --git a/doc/index.org b/doc/index.org index 1cee136..64615d3 100644 --- a/doc/index.org +++ b/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 diff --git a/doc/quickStart.org b/doc/quickStart.org index 0aeb58a..d66b179 100644 --- a/doc/quickStart.org +++ b/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-=. 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-= 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]]. diff --git a/env.el.in b/env.el similarity index 100% rename from env.el.in rename to env.el diff --git a/env.sh.in b/env.sh similarity index 100% rename from env.sh.in rename to env.sh diff --git a/tests/ct-help b/tests/ct-help new file mode 100755 index 0000000..1f0f893 --- /dev/null +++ b/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 \ No newline at end of file