Skip to content

Commit

Permalink
Changes to documentation configuration/generation.
Browse files Browse the repository at this point in the history 
 - One overall documentation switch: ERT_DOC, and subswithces
   ERT_RST_DOC, DOXY_DOC and ERT_DOXY_GRAPHICAL

 - Removed python script to invoke sphinx, invoking sphinx binaries
   directly from cmake.

 - All documentation is in directory documentation/ with subfolders rst/
   and doxy/
  • Loading branch information
@joakim-hove
joakim-hove committed Nov 11, 2016
1 parent a7cdf0f commit a4a795c
Show file tree
Hide file tree
Showing 4 changed files with 67 additions and 58 deletions.
5 changes: 4 additions & 1 deletion CMakeLists.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -215,6 +215,7 @@ if (BUILD_PYTHON)
else()
include(cmake/python.cmake2)
add_subdirectory( python )
if(ERT_DOC)
add_subdirectory( docs )
endif()
Expand All @@ -223,7 +224,9 @@ if (BUILD_PYTHON)
include(GNUInstallDirs)
install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/docs/ecl_summary.1
DESTINATION ${CMAKE_INSTALL_MANDIR}/man1)
endif()
endif()
if(ERT_DOC)
add_subdirectory( docs )
endif()
97 changes: 61 additions & 36 deletions docs/CMakeLists.txt
View file
Original file line number Diff line number Diff line change
@@ -1,45 +1,70 @@
set( ERT_DOC_INSTALL_PATH "" CACHE PATH "Absolute path to install documentation *in addition* to $PREFIX/documentation")
set( ERT_DOC_EXTERNAL_ROOT "" CACHE PATH "Path to site local ERT documentation")

file(MAKE_DIRECTORY "${PROJECT_BINARY_DIR}/tmp_doc")
EXECUTE_PROCESS( COMMAND ${CMAKE_COMMAND} -E create_symlink "${CMAKE_CURRENT_SOURCE_DIR}/user" "${PROJECT_BINARY_DIR}/tmp_doc/user")
EXECUTE_PROCESS( COMMAND ${CMAKE_COMMAND} -E create_symlink "${CMAKE_CURRENT_SOURCE_DIR}/code" "${PROJECT_BINARY_DIR}/tmp_doc/code")

if (ERT_DOC_EXTERNAL_ROOT)
EXECUTE_PROCESS( COMMAND ${CMAKE_COMMAND} -E create_symlink "${ERT_DOC_EXTERNAL_ROOT}" "${PROJECT_BINARY_DIR}/tmp_doc/external-doc")
message(STATUS "Adding documentation link ${PROJECT_BINARY_DIR}/tmp_doc/external-doc -> ${ERT_DOC_EXTERNAL_ROOT}")
set( ERT_DOC_LINK external-doc/index )
else()
set( ERT_DOC_LINK "" )
endif()
option( ERT_RST_DOC "Build RST based documentation" ON)
option( ERT_DOXY_DOC "Build doxygen documentation" ON)
option( ERT_DOXY_GRAPHICAL "Add graphics to doxygen documentation" OFF)

configure_file(index.rst.in ${PROJECT_BINARY_DIR}/tmp_doc/index.rst)
configure_file(conf.py.in ${PROJECT_BINARY_DIR}/conf.py)
if (ERT_RST_DOC)
find_package(Sphinx REQUIRED)
if (SPHINX_FOUND)
set( ERT_DOC_INSTALL_PATH "" CACHE PATH "Absolute path to install documentation *in addition* to $PREFIX/documentation")
set( ERT_DOC_EXTERNAL_ROOT "" CACHE PATH "Path to site local ERT documentation")

add_custom_target(doc_out ALL
COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/script/run-sphinx.py ${PROJECT_BINARY_DIR}/conf.py ${PROJECT_BINARY_DIR}/${PYTHON_INSTALL_PREFIX} ${PROJECT_BINARY_DIR}/tmp_doc
DEPENDS enkf)
file(MAKE_DIRECTORY "${PROJECT_BINARY_DIR}/doc-src")
file(MAKE_DIRECTORY "${PROJECT_BINARY_DIR}/doc-src/_static")
EXECUTE_PROCESS( COMMAND ${CMAKE_COMMAND} -E create_symlink "${CMAKE_CURRENT_SOURCE_DIR}/user" "${PROJECT_BINARY_DIR}/doc-src/user")

INSTALL( DIRECTORY ${PROJECT_BINARY_DIR}/tmp_doc/_build/ DESTINATION ${CMAKE_INSTALL_PREFIX}/documentation )
if (ERT_DOC_EXTERNAL_ROOT)
EXECUTE_PROCESS( COMMAND ${CMAKE_COMMAND} -E create_symlink "${ERT_DOC_EXTERNAL_ROOT}" "${PROJECT_BINARY_DIR}/doc-src/external-doc")
message(STATUS "Adding documentation link ${PROJECT_BINARY_DIR}/doc-src/external-doc -> ${ERT_DOC_EXTERNAL_ROOT}")
set( ERT_DOC_LINK external-doc/index )
else()
set( ERT_DOC_LINK "" )
endif()

if (ERT_DOC_INSTALL_PATH)
INSTALL( DIRECTORY ${PROJECT_BINARY_DIR}/tmp_doc/_build/ DESTINATION ${ERT_DOC_INSTALL_PATH} )
endif()
configure_file(index.rst.in ${PROJECT_BINARY_DIR}/doc-src/index.rst)
configure_file(conf.py.in ${PROJECT_BINARY_DIR}/doc-src/conf.py)

if (BUILD_PYTHON)
EXECUTE_PROCESS( COMMAND ${CMAKE_COMMAND} -E create_symlink "${CMAKE_CURRENT_SOURCE_DIR}/code" "${PROJECT_BINARY_DIR}/doc-src/code")
add_custom_target(api-doc ALL
COMMAND sphinx-apidoc -e -o doc-src/API/python ${PROJECT_BINARY_DIR}/${PYTHON_INSTALL_PREFIX}
DEPENDS enkf)
endif()

add_custom_target(rst-doc ALL
COMMAND sphinx-build -b html -d doc-src/doctrees doc-src documentation/rst
WORKING_DIRECTORY ${PROJECT_BINARY_DIR})

find_package(Doxygen)
if (DOXYGEN_FOUND)
message(STATUS "Creating doxygen target")
if (DOXYGEN_DOT_FOUND)
message(STATUS "Found graphviz, will run doxygen with graphics")
set( DOXYGEN_HAVE_DOT "YES" )
else()
message(STATUS "Graphviz not found, disabling dot")
set( DOXYGEN_HAVE_DOT "NO" )
message(STATUS "Sphinx documentation tool not found - documentation not generated")
endif()
endif()


if (ERT_DOXY_DOC)
find_package(Doxygen)
if (DOXYGEN_FOUND)

configure_file(doxygen.cfg.in ${PROJECT_BINARY_DIR}/doxygen.cfg)
add_custom_target(doxy
COMMAND ${DOXYGEN_EXECUTABLE} ${PROJECT_BINARY_DIR}/doxygen.cfg
WORKING_DIRECTORY ${PROJECT_BINARY_DIR}/../
COMMENT "Generating doxygen documentation")
set( DOXYGEN_HAVE_DOT "NO" )
if ( ERT_DOXY_GRAPHICAL)
if (DOXYGEN_DOT_FOUND)
set( DOXYGEN_HAVE_DOT "YES" )
endif()
endif()

if (BUILD_ERT)
SET( DOXYGEN_INPUT "${PROJECT_SOURCE_DIR}/libanalysis ${PROJECT_SOURCE_DIR}/libconfig ${PROJECT_SOURCE_DIR}/libecl ${PROJECT_SOURCE_DIR}/libecl_well ${PROJECT_SOURCE_DIR}/libeclxx ${PROJECT_SOURCE_DIR}/libenkf ${PROJECT_SOURCE_DIR}/libert_util ${PROJECT_SOURCE_DIR}/libert_utilxx ${PROJECT_SOURCE_DIR}/libgeometry ${PROJECT_SOURCE_DIR}/libjob_queue ${PROJECT_SOURCE_DIR}/librms ${PROJECT_SOURCE_DIR}/libsched")
else()
SET( DOXYGEN_INPUT "${PROJECT_SOURCE_DIR}/libecl ${PROJECT_SOURCE_DIR}/libecl_well ${PROJECT_SOURCE_DIR}/libeclxx ${PROJECT_SOURCE_DIR}/libert_util ${PROJECT_SOURCE_DIR}/libert_utilxx ${PROJECT_SOURCE_DIR}/libgeometry")
endif()

configure_file(doxygen.cfg.in ${PROJECT_BINARY_DIR}/doxygen.cfg)
add_custom_target(doxy ALL
COMMAND ${DOXYGEN_EXECUTABLE} ${PROJECT_BINARY_DIR}/doxygen.cfg
WORKING_DIRECTORY ${PROJECT_BINARY_DIR}/../
COMMENT "Generating doxygen documentation")

endif()
endif()


INSTALL( DIRECTORY ${PROJECT_BINARY_DIR}/documentation DESTINATION ${CMAKE_INSTALL_PREFIX} )
4 changes: 2 additions & 2 deletions docs/doxygen.cfg.in
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ PROJECT_NAME = "Ert"
PROJECT_NUMBER = ${ERT_VERSION_MAJOR}.${ERT_VERSION_MINOR}
PROJECT_BRIEF = "ERT is a software initially developed by Statoil which main feature is to handle several ECLIPSE simulations in an Ensemble setting. --- http://ert.nr.no/ert"
PROJECT_LOGO =
OUTPUT_DIRECTORY = ${PROJECT_BINARY_DIR}/doxy
OUTPUT_DIRECTORY = ${PROJECT_BINARY_DIR}/documentation/doxy
CREATE_SUBDIRS = NO
STRIP_FROM_PATH =
STRIP_FROM_INC_PATH =
Expand All @@ -25,7 +25,7 @@ WARN_IF_DOC_ERROR = NO
WARN_NO_PARAMDOC = NO
WARN_FORMAT = "$file:$line: $text"

INPUT = ${PROJECT_SOURCE_DIR}/libanalysis ${PROJECT_SOURCE_DIR}/libconfig ${PROJECT_SOURCE_DIR}/libecl ${PROJECT_SOURCE_DIR}/libecl_well ${PROJECT_SOURCE_DIR}/libeclxx ${PROJECT_SOURCE_DIR}/libenkf ${PROJECT_SOURCE_DIR}/libert_util ${PROJECT_SOURCE_DIR}/libert_utilxx ${PROJECT_SOURCE_DIR}/libgeometry ${PROJECT_SOURCE_DIR}/libjob_queue ${PROJECT_SOURCE_DIR}/librms ${PROJECT_SOURCE_DIR}/libsched
INPUT = ${DOXYGEN_INPUT}

RECURSIVE = YES
EXCLUDE_PATTERNS = */test/* */build/* */test-data/* */docs/* */python*/
Expand Down
19 changes: 0 additions & 19 deletions docs/script/run-sphinx.py
View file

This file was deleted.

0 comments on commit a4a795c

Please sign in to comment.