Documentation build modifications:

- add macro "_add_doxy_headers" in order to track all header files elligible for
  doxygen documenation. This captures public header files that would otherwise be
  excluded from installation because they are not supported by the OS. Private
  header files remain excluded though.

- add custom targets and commands so that documentation build produces functioning
  RST and Doxygen documentation both in the build and install stages

- switched to Doxygen 1.8 (because markdown will make in-lined documentation easier)

- added build switches to disable examples, regression and python-SWIG targets

- fixed doxygen link in the nav bar

- modified python html processing tool to match Cmake changes
This commit is contained in:
manuelk 2013-07-05 15:36:54 -07:00
parent efb1a5fe44
commit 9712b44239
10 changed files with 1211 additions and 935 deletions

View File

@ -255,7 +255,7 @@ find_package(GLFW 2.7.0)
find_package(PTex 2.0)
find_package(PythonInterp 2.6)
find_package(SWIG 1.3.40)
find_package(Doxygen)
find_package(Doxygen 1.8.4)
find_package(Docutils 0.6)
if (NOT APPLE AND OPENGL_FOUND)
find_package(GLEW REQUIRED)
@ -383,7 +383,7 @@ else()
)
endif()
if(PYTHONINTERP_FOUND AND SWIG_FOUND)
if(PYTHONINTERP_FOUND AND SWIG_FOUND AND NOT NO_PYTHON)
message(STATUS "Python and SWIG found. Looking for numpy...")
execute_process(
COMMAND
@ -432,12 +432,6 @@ if(PYTHONINTERP_FOUND AND SWIG_FOUND)
COMMAND ${PYCMD} install --user)"
)
endif()
else()
message(WARNING
"Python / Swig not found : python bindings and examples will not be "
"available. If you do have Python and Swig installed and see this "
"message, please check the default FindPython.cmake module."
)
endif()
# Link examples & regressions dynamically against Osd
@ -472,6 +466,43 @@ endif()
#-------------------------------------------------------------------------------
# General-use macros
# Macro for processing public headers into the build area for doxygen processing
add_custom_target( public_headers )
macro(_add_doxy_headers headers)
file(RELATIVE_PATH path ${CMAKE_SOURCE_DIR} ${CMAKE_CURRENT_SOURCE_DIR} )
string(REPLACE "/" "_" targetpath ${path})
foreach (header ${headers})
set(infile ${CMAKE_CURRENT_SOURCE_DIR}/${header})
set(outfile ${CMAKE_BINARY_DIR}/public_headers/${path}/${header})
set(targetname "${targetpath}_${header}")
add_custom_command(
OUTPUT
${outfile}
COMMAND
${CMAKE_COMMAND}
ARGS
-E copy ${infile} ${outfile}
DEPENDS
${infile}
)
add_custom_target(${targetname} DEPENDS ${outfile})
list(APPEND headerfiles ${targetname} )
endforeach()
add_dependencies( public_headers DEPENDS ${headerfiles} )
endmacro()
# Macro for adding a cuda executable if cuda is found and a regular
# executable otherwise.
macro(_add_possibly_cuda_executable target)
@ -522,10 +553,12 @@ endmacro()
add_subdirectory(opensubdiv)
if(NOT ANDROID AND NOT IOS) # XXXdyu
if (NOT NO_REGRESSION AND NOT ANDROID AND NOT IOS) # XXXdyu
add_subdirectory(regression)
endif()
add_subdirectory(examples)
if (NOT NO_EXAMPLES)
add_subdirectory(examples)
endif()
add_subdirectory(documentation)

View File

@ -64,12 +64,21 @@ if (NOT NO_DOC)
add_custom_target(doc_doxy
${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/OpenSubdiv.doxy
WORKING_DIRECTORY
${CMAKE_INSTALL_PREFIX}/include
${CMAKE_BINARY_DIR}/public_headers/
DEPENDS
public_headers
COMMENT
"Generating API documentation with Doxygen" VERBATIM
)
list(APPEND DOC_TARGETS doc_doxy)
install(
DIRECTORY
${CMAKE_CURRENT_BINARY_DIR}/doxy_html
DESTINATION
${CMAKE_INSTALL_PREFIX}/documentation
)
else()
@ -80,7 +89,7 @@ if (NOT NO_DOC)
if (DOCUTILS_FOUND)
if (DOCUTILS_FOUND AND PYTHONINTERP_FOUND)
set(HTML_FILES
search.html
@ -125,7 +134,7 @@ if (NOT NO_DOC)
${infile}
)
add_custom_target(${src} ALL DEPENDS ${outfile})
add_custom_target(${src} DEPENDS ${outfile})
list(APPEND RST_TARGETS ${src})
@ -154,7 +163,7 @@ if (NOT NO_DOC)
-E copy ${infile} ${outfile}
)
add_custom_target( ${src} ALL DEPENDS ${outfile})
add_custom_target( ${src} DEPENDS ${outfile})
list(APPEND HTML_TARGETS ${src})
@ -166,41 +175,62 @@ if (NOT NO_DOC)
)
endforeach()
# copy the site resources to the build area so that the
# documentation can be read without an install
add_custom_target(doc_html_images
COMMAND
${CMAKE_COMMAND} -E copy_directory ${CMAKE_CURRENT_SOURCE_DIR}/images ${CMAKE_CURRENT_BINARY_DIR}/images
)
add_custom_target(doc_html_css
COMMAND
${CMAKE_COMMAND} -E copy_directory ${CMAKE_CURRENT_SOURCE_DIR}/css ${CMAKE_CURRENT_BINARY_DIR}/css
)
add_custom_target(doc_tipuesearch
COMMAND
${CMAKE_COMMAND} -E copy_directory ${CMAKE_CURRENT_SOURCE_DIR}/tipuesearch ${CMAKE_CURRENT_BINARY_DIR}/tipuesearch
)
# build search index and insert navigation tab
if (PYTHONINTERP_FOUND)
add_custom_target(search_index
COMMAND
${PYTHON_EXECUTABLE}
${CMAKE_CURRENT_SOURCE_DIR}/processHtml.py
${CMAKE_CURRENT_BINARY_DIR}
${CMAKE_CURRENT_SOURCE_DIR}/nav_template.txt
DEPENDS
${HTML_TARGETS} ${RST_TARGETS} doc_tipuesearch
)
add_custom_target(doc_html
DEPENDS
search_index
${HTML_TARGETS}
${RST_TARGETS}
doc_html_images
doc_html_css
doc_tipuesearch
)
install(
DIRECTORY
${CMAKE_CURRENT_BINARY_DIR}/tipuesearch
DESTINATION
${CMAKE_INSTALL_PREFIX}/documentation
)
add_custom_target(search_index ALL
COMMAND
${PYTHON_EXECUTABLE}
${CMAKE_CURRENT_SOURCE_DIR}/processHtml.py
${CMAKE_CURRENT_BINARY_DIR}
${CMAKE_INSTALL_PREFIX}/documentation
${CMAKE_CURRENT_SOURCE_DIR}/nav_template.txt
DEPENDS
${HTML_TARGETS} ${RST_TARGETS}
)
install(
DIRECTORY
tipuesearch
DESTINATION
${CMAKE_INSTALL_PREFIX}/documentation
)
endif()
add_custom_target(doc_html DEPENDS ${HTML_TARGETS} ${RST_TARGETS} )
install(
DIRECTORY
images
${CMAKE_CURRENT_BINARY_DIR}/images
DESTINATION
${CMAKE_INSTALL_PREFIX}/documentation
)
install(
DIRECTORY
css
${CMAKE_CURRENT_BINARY_DIR}/css
DESTINATION
${CMAKE_INSTALL_PREFIX}/documentation
)
@ -208,6 +238,6 @@ if (NOT NO_DOC)
list(APPEND DOC_TARGETS doc_html)
endif()
add_custom_target(doc DEPENDS ${DOC_TARGETS})
add_custom_target(doc ALL DEPENDS ${DOC_TARGETS})
endif()

File diff suppressed because it is too large Load Diff

View File

@ -142,9 +142,12 @@ The following configuration arguments can be passed to the cmake command line.
-DGLFW_LOCATION=[path to GLFW]
-DMAYA_LOCATION=[path to Maya]
-DNO_OMP=1 // disable OpenMP
-DNO_GCD=1 // disable GrandCentralDispatch on OSX
-DNO_DOC=1 // disable documentation build
-DNO_EXAMPLES=1 // disable examples build
-DNO_REGRESSION=1 // disable regression tests build
-DNO_PYTHON=1 // disable Python SWIG build
-DNO_DOC=1 // disable documentation build
-DNO_OMP=1 // disable OpenMP
-DNO_GCD=1 // disable GrandCentralDispatch on OSX
Environment Variables
_____________________

View File

@ -104,7 +104,7 @@
<hr>
<li><a href="release_notes.html">Release Notes</a>
<hr>
<li><a href="html/index.html">Doxygen</a></li>
<li><a href="doxy_html/index.html" target="_blank">Doxygen</a></li>
</ul>
</div>
<hr>

View File

@ -138,17 +138,20 @@ if (len(sys.argv)<3):
rootDir = str(sys.argv[1])
outputDir = str(sys.argv[2])
f = open( str(sys.argv[3]), "r")
f = open( str(sys.argv[2]), "r")
navHtml = f.read()
f.close()
print "rootDir="+rootDir+" outputDir="+outputDir
print "Scanning :"+rootDir
searchIndex = 'var tipuesearch = { "pages": [ '
for root, dirs, files in os.walk(rootDir):
# skip doxygen generated HTML
if 'doxy_html' in dirs:
dirs.remove('doxy_html')
for f in files:
inputFile = os.path.join(root, f)
@ -191,5 +194,5 @@ for root, dirs, files in os.walk(rootDir):
searchIndex = searchIndex + "]};"
WriteIndexFile( os.path.join(outputDir, "tipuesearch", "tipuesearch_content.js"), searchIndex )
WriteIndexFile( os.path.join(rootDir, "tipuesearch", "tipuesearch_content.js"), searchIndex )

View File

@ -55,6 +55,7 @@
# a particular purpose and non-infringement.
#
#-------------------------------------------------------------------------------
set(PUBLIC_HEADER_FILES
bilinearSubdivisionTables.h
bilinearSubdivisionTablesFactory.h
@ -78,6 +79,11 @@ set(PUBLIC_HEADER_FILES
vertexEditTablesFactory.h
)
#-------------------------------------------------------------------------------
_add_doxy_headers( "${PUBLIC_HEADER_FILES}" )
install( FILES ${PUBLIC_HEADER_FILES}
DESTINATION ${CMAKE_INCDIR_BASE}/far
PERMISSIONS OWNER_READ GROUP_READ WORLD_READ )
#-------------------------------------------------------------------------------

View File

@ -55,6 +55,7 @@
# a particular purpose and non-infringement.
#
#-------------------------------------------------------------------------------
set(PUBLIC_HEADER_FILES
allocator.h
bilinear.h
@ -75,6 +76,11 @@ set(PUBLIC_HEADER_FILES
vertex.h
)
#-------------------------------------------------------------------------------
_add_doxy_headers( "${PUBLIC_HEADER_FILES}" )
install( FILES ${PUBLIC_HEADER_FILES}
DESTINATION ${CMAKE_INCDIR_BASE}/hbr
PERMISSIONS OWNER_READ GROUP_READ WORLD_READ )
#-------------------------------------------------------------------------------

View File

@ -136,7 +136,12 @@ add_definitions(
${PLATFORM_COMPILE_FLAGS}
)
set(DOXY_HEADER_FILES ${PUBLIC_HEADER_FILES})
#-------------------------------------------------------------------------------
set(GL_PTEX_PUBLIC_HEADERS glPtexTexture.h)
set(DX_PTEX_PUBLIC_HEADERS d3d11PtexTexture.h)
if( PTEX_FOUND )
list(APPEND CPU_SOURCE_FILES
ptexTextureLoader.cpp
@ -146,7 +151,7 @@ if( PTEX_FOUND )
glPtexTexture.cpp
)
list(APPEND PUBLIC_HEADER_FILES
glPtexTexture.h
${GL_PTEX_PUBLIC_HEADERS}
)
endif()
if( DXSDK_FOUND )
@ -154,7 +159,7 @@ if( PTEX_FOUND )
d3d11PtexTexture.cpp
)
list(APPEND PUBLIC_HEADER_FILES
d3d11PtexTexture.h
${DX_PTEX_PUBLIC_HEADERS}
)
endif()
include_directories( ${PTEX_INCLUDE_DIR} )
@ -163,16 +168,25 @@ if( PTEX_FOUND )
)
endif()
list(APPEND DOXY_HEADER_FILES
${GL_PTEX_PUBLIC_HEADERS}
${DX_PTEX_PUBLIC_HEADERS}
)
#-------------------------------------------------------------------------------
set(OPENMP_PUBLIC_HEADERS
ompKernel.h
ompComputeController.h
)
if( OPENMP_FOUND )
list(APPEND CPU_SOURCE_FILES
ompKernel.cpp
ompComputeController.cpp
)
list(APPEND PUBLIC_HEADER_FILES
ompKernel.h
ompComputeController.h
)
list(APPEND PUBLIC_HEADER_FILES ${OPENMP_PUBLIC_HEADERS})
if (CMAKE_COMPILER_IS_GNUCXX)
list(APPEND PLATFORM_LIBRARIES
gomp
@ -180,20 +194,34 @@ if( OPENMP_FOUND )
endif()
endif()
list(APPEND DOXY_HEADER_FILES ${OPENMP_PUBLIC_HEADERS})
#-------------------------------------------------------------------------------
set(GCD_PUBLIC_HEADERS
gcdKernel.h
gcdComputeController.h
)
if( GCD_FOUND )
list(APPEND CPU_SOURCE_FILES
gcdKernel.cpp
gcdComputeController.cpp
)
list(APPEND PUBLIC_HEADER_FILES
gcdKernel.h
gcdComputeController.h
)
list(APPEND PUBLIC_HEADER_FILES ${GCD_PUBLIC_HEADERS})
endif()
list(APPEND DOXY_HEADER_FILES ${GCD_PUBLIC_HEADERS})
#-------------------------------------------------------------------------------
# GL code & dependencies
set(GL_PUBLIC_HEADERS
cpuGLVertexBuffer.h
glDrawContext.h
glDrawRegistry.h
glVertexBuffer.h
glMesh.h
)
if( OPENGL_FOUND OR OPENGLES_FOUND )
list(APPEND GPU_SOURCE_FILES
cpuGLVertexBuffer.cpp
@ -201,13 +229,7 @@ if( OPENGL_FOUND OR OPENGLES_FOUND )
glDrawRegistry.cpp
glVertexBuffer.cpp
)
list(APPEND PUBLIC_HEADER_FILES
cpuGLVertexBuffer.h
glDrawContext.h
glDrawRegistry.h
glVertexBuffer.h
glMesh.h
)
list(APPEND PUBLIC_HEADER_FILES ${GL_PUBLIC_HEADERS})
if ( OPENGL_FOUND )
list(APPEND KERNEL_FILES
glslPatchCommon.glsl
@ -222,20 +244,24 @@ if( OPENGL_FOUND OR OPENGLES_FOUND )
)
endif()
list(APPEND DOXY_HEADER_FILES ${GL_PUBLIC_HEADERS})
#-------------------------------------------------------------------------------
# OpenGL 4.2 dependencies
# note : (GLSL transform feedback kernels require GL 4.2)
set(GL_4_2_PUBLIC_HEADERS
glslTransformFeedbackComputeContext.h
glslTransformFeedbackComputeController.h
glslTransformFeedbackKernelBundle.h
)
if( OPENGL_4_2_FOUND )
list(APPEND GPU_SOURCE_FILES
glslTransformFeedbackComputeController.cpp
glslTransformFeedbackComputeContext.cpp
glslTransformFeedbackKernelBundle.cpp
)
list(APPEND PUBLIC_HEADER_FILES
glslTransformFeedbackComputeContext.h
glslTransformFeedbackComputeController.h
glslTransformFeedbackKernelBundle.h
)
list(APPEND PUBLIC_HEADER_FILES ${GL_4_2_PUBLIC_HEADERS})
list(APPEND KERNEL_FILES
glslTransformFeedbackKernel.glsl
)
@ -244,20 +270,24 @@ if( OPENGL_4_2_FOUND )
)
endif()
list(APPEND DOXY_HEADER_FILES ${GL_4_2_PUBLIC_HEADERS})
#-------------------------------------------------------------------------------
# OpenGL 4.3 dependencies
# note : (GLSL compute shader kernels require GL 4.3)
set(GL_4_3_PUBLIC_HEADERS
glslComputeContext.h
glslComputeController.h
glslKernelBundle.h
)
if( OPENGL_4_3_FOUND )
list(APPEND GPU_SOURCE_FILES
glslComputeController.cpp
glslComputeContext.cpp
glslKernelBundle.cpp
)
list(APPEND PUBLIC_HEADER_FILES
glslComputeContext.h
glslComputeController.h
glslKernelBundle.h
)
list(APPEND PUBLIC_HEADER_FILES ${GL_4_3_PUBLIC_HEADERS})
list(APPEND KERNEL_FILES
glslComputeKernel.glsl
)
@ -266,8 +296,20 @@ if( OPENGL_4_3_FOUND )
)
endif()
list(APPEND DOXY_HEADER_FILES ${GL_4_3_PUBLIC_HEADERS})
#-------------------------------------------------------------------------------
# DX11 code & dependencies
set(DXSDK_PUBLIC_HEADERS
cpuD3D11VertexBuffer.h
d3d11ComputeContext.h
d3d11ComputeController.h
d3d11DrawContext.h
d3d11DrawRegistry.h
d3d11KernelBundle.h
d3d11VertexBuffer.h
d3d11Mesh.h
)
if( DXSDK_FOUND )
list(APPEND GPU_SOURCE_FILES
cpuD3D11VertexBuffer.cpp
@ -278,16 +320,7 @@ if( DXSDK_FOUND )
d3d11KernelBundle.cpp
d3d11VertexBuffer.cpp
)
list(APPEND PUBLIC_HEADER_FILES
cpuD3D11VertexBuffer.h
d3d11ComputeContext.h
d3d11ComputeController.h
d3d11DrawContext.h
d3d11DrawRegistry.h
d3d11KernelBundle.h
d3d11VertexBuffer.h
d3d11Mesh.h
)
list(APPEND PUBLIC_HEADER_FILES ${DXSDK_PUBLIC_HEADERS})
list(APPEND KERNEL_FILES
hlslComputeKernel.hlsl
hlslPatchCommon.hlsl
@ -300,8 +333,15 @@ if( DXSDK_FOUND )
)
endif()
list(APPEND DOXY_HEADER_FILES ${DXSDK_PUBLIC_HEADERS})
#-------------------------------------------------------------------------------
# OpenCL code & dependencies
set(OPENCL_PUBLIC_HEADERS
clComputeContext.h
clComputeController.h
clVertexBuffer.h
)
if ( OPENCL_FOUND )
list(APPEND GPU_SOURCE_FILES
clComputeController.cpp
@ -309,11 +349,7 @@ if ( OPENCL_FOUND )
clKernelBundle.cpp
clVertexBuffer.cpp
)
list(APPEND PUBLIC_HEADER_FILES
clComputeContext.h
clComputeController.h
clVertexBuffer.h
)
list(APPEND PUBLIC_HEADER_FILES ${OPENCL_PUBLIC_HEADERS})
list(APPEND KERNEL_FILES
clKernel.cl
)
@ -331,19 +367,22 @@ if ( OPENCL_FOUND )
endif()
endif()
list(APPEND DOXY_HEADER_FILES ${OPENCL_PUBLIC_HEADERS})
#-------------------------------------------------------------------------------
# CUDA code & dependencies
set(CUDA_PUBLIC_HEADERS
cudaComputeContext.h
cudaComputeController.h
cudaVertexBuffer.h
)
if( CUDA_FOUND )
list(APPEND GPU_SOURCE_FILES
cudaComputeController.cpp
cudaComputeContext.cpp
cudaVertexBuffer.cpp
)
list(APPEND PUBLIC_HEADER_FILES
cudaComputeContext.h
cudaComputeController.h
cudaVertexBuffer.h
)
list(APPEND PUBLIC_HEADER_FILES ${CUDA_PUBLIC_HEADERS})
list(APPEND KERNEL_FILES
cudaKernel.cu
)
@ -370,6 +409,7 @@ if( CUDA_FOUND )
endif()
endif()
list(APPEND DOXY_HEADER_FILES ${CUDA_PUBLIC_HEADERS})
#-------------------------------------------------------------------------------
# Kernel Stringification
@ -461,6 +501,7 @@ if (NOT WIN32 AND NOT IOS)
install( TARGETS osd_dynamic_gpu DESTINATION ${CMAKE_LIBDIR_BASE} )
endif()
_add_doxy_headers( "${DOXY_HEADER_FILES}" )
install( FILES ${PUBLIC_HEADER_FILES}
DESTINATION ${CMAKE_INCDIR_BASE}/osd

View File

@ -70,21 +70,30 @@ set(PUBLIC_HEADER_FILES
drawController.h
)
#-------------------------------------------------------------------------------
# OpenCL code & dependencies
if ( OPENCL_FOUND )
list(APPEND PUBLIC_HEADER_FILES
batchCL.h
)
endif()
set(DOXY_HEADER_FILES ${PUBLIC_HEADER_FILES})
#-------------------------------------------------------------------------------
# platform dependent tweaks
# OpenCL code & dependencies
set(OPENCL_PUBLIC_HEADER_FILES
batchCL.h
)
if ( OPENCL_FOUND )
list(APPEND PUBLIC_HEADER_FILES ${OPENCL_PUBLIC_HEADER_FILES} )
endif()
list(APPEND DOXY_HEADER_FILES ${OPENCL_PUBLIC_HEADER_FILES} )
#-------------------------------------------------------------------------------
_add_doxy_headers( "${DOXY_HEADER_FILES}" )
install( FILES ${PUBLIC_HEADER_FILES}
DESTINATION include/osdutil
PERMISSIONS OWNER_READ GROUP_READ WORLD_READ )
# platform dependent tweaks
if (ANDROID)
install( FILES Android.mk
DESTINATION ${LIBRARY_OUTPUT_PATH_ROOT}