Add new 'doc' target for generating Urho3D documentation.

make clean make all make doc <-- New target make install
2013-11-24 21:12:05 +08:00 · 2013-11-24 21:12:05 +08:00 · 19e1e42ca3
commit 19e1e42ca3
parent 98b517af3a
7 changed files with 86 additions and 23 deletions
--- a/.gitignore
+++ b/.gitignore
@ -26,7 +26,7 @@ Lib-CC/

 # Generated documentation
 Docs/html/
-Doxyfile
+Docs/Doxyfile

 # Eclipse project settings
 Source/.*project
--- a/Bin/UpdateDocument.bat
+++ b/Bin/UpdateDocument.bat
@ -1,11 +1,12 @@
@echo off
+cd ..\Docs
 echo "Dumping AngelScript API..."
-ScriptCompiler -dumpapi ../Docs/ScriptAPI.dox ../Docs/AngelScriptAPI.h
+..\Bin\ScriptCompiler -dumpapi ScriptAPI.dox AngelScriptAPI.h
 if errorlevel 1 exit /B 1
 lua -v 1>nul 2>&1
 if %errorlevel%== 0 (
    echo "Dumping LuaScript API..."
-    set "out=%cd%/../Docs/LuaScriptAPI.dox"
+    set "out=%cd%\LuaScriptAPI.dox"
    pushd ..\Source\Engine\LuaScript\pkgs
    lua pkgToDox.lua %out% *.pkg
    if errorlevel 1 exit /B 1
@ -13,5 +14,5 @@ if %errorlevel%== 0 (
 )
 if not "%1" == "-a" exit /B 0
 echo "Converting Doxygen files to HTML..."
-cd .. && doxygen Doxyfile 1>nul
+doxygen Doxyfile 1>nul
 echo "Finish."
--- a/Bin/UpdateDocument.sh
+++ b/Bin/UpdateDocument.sh
@ -1,11 +1,11 @@
-cd $( dirname $0 )
+cd $( dirname $0 )/../Docs
 echo "Dumping AngelScript API..."
-./ScriptCompiler -dumpapi ../Docs/ScriptAPI.dox ../Docs/AngelScriptAPI.h
+../Bin/ScriptCompiler -dumpapi ScriptAPI.dox AngelScriptAPI.h
 if [ $? -ne 0 ]; then exit 1; fi
 lua -v 1>/dev/null 2>&1
 if [ $? -eq 0 ]; then
    echo "Dumping LuaScript API..."
-    out=`pwd`/../Docs/LuaScriptAPI.dox
+    out=`pwd`/LuaScriptAPI.dox
    pushd ../Source/Engine/LuaScript/pkgs >/dev/null
    lua pkgToDox.lua $out *.pkg
    if [ $? -ne 0 ]; then exit 1; fi
@ -13,5 +13,5 @@ if [ $? -eq 0 ]; then
 fi
 if [ "$1" != "-a" ]; then exit 0; fi
 echo "Converting Doxygen files to HTML..."
-cd .. && doxygen Doxyfile 1>/dev/null
+doxygen Doxyfile 1>/dev/null
 echo "Finish."
--- a/Docs/CMakeLists.txt
+++ b/Docs/CMakeLists.txt
@ -0,0 +1,70 @@
+#
+# Copyright (c) 2008-2013 the Urho3D project.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+
+# Set project name
+project (Urho3D-Docs)
+
+# There could be bug in CMake find_package() command, it currently does not honor NO_CMAKE_FIND_ROOT_PATH option for a non-rooted search as per CMake's documentation
+# As a workaround, we unset CMAKE_FIND_ROOT_PATH in this scope ONLY to always do a non-rooted search for Doxygen package (even when we are cross-compiling)
+unset (CMAKE_FIND_ROOT_PATH)
+# Find Doxygen and DOT packages
+find_package (Doxygen QUIET)
+
+if (DOXYGEN_FOUND)
+    # Generate platform specific Doxyfile automatically
+    if (NOT USE_OPENGL EQUAL DOXYFILE_USE_OPENGL OR ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in IS_NEWER_THAN ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+        set (DOXYFILE_USE_OPENGL ${USE_OPENGL} CACHE INTERNAL "USE_OPENGL flag when Doxyfile was last generated")
+        if (USE_OPENGL)
+            set (EXCLUDE_GRAPHICS_API Direct3D9)
+        else ()
+            set (EXCLUDE_GRAPHICS_API OpenGL)
+        endif ()
+        configure_file (${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile) 
+    endif ()
+
+    # Dump AngelScript and LuaScript API to Doxygen file if the tool is available
+    if (TARGET ScriptCompiler)
+        add_custom_command (OUTPUT ScriptAPI.dox
+            COMMAND ${PROJECT_ROOT_DIR}/Bin/ScriptCompiler -dumpapi ScriptAPI.dox AngelScriptAPI.h DEPENDS Urho3D ScriptCompiler
+            WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+            COMMENT "Dumping AngelScript API to ScriptAPI.dox")
+    endif ()
+    execute_process (COMMAND lua -v RESULT_VARIABLE LUA_EXIT_CODE OUTPUT_QUIET ERROR_QUIET)
+    if (LUA_EXIT_CODE EQUAL 0)
+        add_custom_command (OUTPUT LuaScriptAPI.dox
+            COMMAND lua pkgToDox.lua ${CMAKE_CURRENT_BINARY_DIR}/LuaScriptAPI.dox *.pkg DEPENDS Urho3D
+            WORKING_DIRECTORY ${PROJECT_ROOT_DIR}/Source/Engine/LuaScript/pkgs
+            COMMENT "Dumping LuaScript API to LuaScriptAPI.dox")
+    endif ()
+    
+    # Add custom 'doc' target for generating Urho3D documentation
+    add_custom_target (doc
+        COMMAND ${DOXYGEN_EXECUTABLE} Doxyfile DEPENDS ScriptAPI.dox LuaScriptAPI.dox
+        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+        COMMENT "Generating documentation with Doxygen")
+endif ()
+
+# Make sure html output directory exists and not empty
+file (WRITE ${CMAKE_CURRENT_BINARY_DIR}/html/Readme.txt "Use 'make doc' command or an equivalent command in IDE to re-generate Urho3D documentation.")
+    
+# Currently it is not possible to make built-in 'install' target to depends on 'doc' in CMake, therefore 'make doc' command need to be invoked manually before 'make install' in order to install the SDK with complete documentation
+install (DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/ DESTINATION ${DEST_SHARE_DIR}/Docs USE_SOURCE_PERMISSIONS)
--- a/Docs/Doxyfile.in
+++ b/Docs/Doxyfile.in
@ -52,7 +52,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       = Docs
+OUTPUT_DIRECTORY       = .

 # 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 
@ -665,8 +665,8 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.

-INPUT                  = Source/Engine \
-                         Docs
+INPUT                  = ../Source/Engine \
+                         .

 # 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 
--- a/Source/CMakeLists.txt
+++ b/Source/CMakeLists.txt
@ -112,13 +112,5 @@ if (NOT IOS AND NOT ANDROID AND ENABLE_EXTRAS)
    add_subdirectory (Extras)
 endif ()

-# Generate platform specific Doxyfile automatically
-if (NOT USE_OPENGL EQUAL DOXYFILE_USE_OPENGL OR ${PROJECT_ROOT_DIR}/Docs/Doxyfile.in IS_NEWER_THAN ${PROJECT_ROOT_DIR}/Doxyfile)
-    set (DOXYFILE_USE_OPENGL ${USE_OPENGL} CACHE INTERNAL "USE_OPENGL flag when Doxyfile was last generated")
-    if (USE_OPENGL)
-        set (EXCLUDE_GRAPHICS_API Direct3D9)
-    else ()
-        set (EXCLUDE_GRAPHICS_API OpenGL)
-    endif ()
-    configure_file (${PROJECT_ROOT_DIR}/Docs/Doxyfile.in ${PROJECT_ROOT_DIR}/Doxyfile) 
-endif ()
+# Urho3D documentation
+add_subdirectory (../Docs ../Docs)
--- a/cmake_gcc.sh
+++ b/cmake_gcc.sh
@ -42,9 +42,9 @@ GENERATOR="Unix Makefiles"

 # Create project with the respective CMake generators
 OPT=
-msg "Native build" && cmake -E chdir Build cmake $OPT -G $GENERATOR $PLATFORM $@ $SOURCE && post_cmake Build
-[ $RASPI_TOOL ] && msg "Raspberry Pi build" && cmake -E chdir raspi-Build cmake $OPT -G $GENERATOR -DRASPI=1 -DCMAKE_TOOLCHAIN_FILE=$SOURCE/CMake/Toolchains/raspberrypi.toolchain.cmake $@ $SOURCE && post_cmake raspi-Build
 [ $ANDROID_NDK ] && msg "Android build" && cmake -E chdir android-Build cmake $OPT -G $GENERATOR -DANDROID=1 -DCMAKE_TOOLCHAIN_FILE=$SOURCE/CMake/Toolchains/android.toolchain.cmake -DLIBRARY_OUTPUT_PATH_ROOT=. $@ $SOURCE && post_cmake android-Build
+[ $RASPI_TOOL ] && msg "Raspberry Pi build" && cmake -E chdir raspi-Build cmake $OPT -G $GENERATOR -DRASPI=1 -DCMAKE_TOOLCHAIN_FILE=$SOURCE/CMake/Toolchains/raspberrypi.toolchain.cmake $@ $SOURCE && post_cmake raspi-Build
+msg "Native build" && cmake -E chdir Build cmake $OPT -G $GENERATOR $PLATFORM $@ $SOURCE && post_cmake Build
 unset IFS

 # Create symbolic links in the build directories