| # Building docs script |
| # Requirements: |
| # sudo apt-get install doxygen texlive ruby-dev |
| # sudo gem install jekyll execjs therubyracer |
|
|
| if(NOT BUILD_docs OR NOT DOXYGEN_FOUND) |
| return() |
| endif() |
|
|
| ################################################################################################# |
| # Gather docs from <root>/examples/**/readme.md |
| function(gather_readmes_as_prebuild_cmd target gathered_dir root) |
| set(full_gathered_dir ${root}/${gathered_dir}) |
|
|
| file(GLOB_RECURSE readmes ${root}/examples/readme.md ${root}/examples/README.md) |
| foreach(file ${readmes}) |
| # Only use file if it is to be included in docs. |
| file(STRINGS ${file} file_lines REGEX "include_in_docs: true") |
|
|
| if(file_lines) |
| # Since everything is called readme.md, rename it by its dirname. |
| file(RELATIVE_PATH file ${root} ${file}) |
| get_filename_component(folder ${file} PATH) |
| set(new_filename ${full_gathered_dir}/${folder}.md) |
|
|
| # folder value might be like <subfolder>/readme.md. That's why make directory. |
| get_filename_component(new_folder ${new_filename} PATH) |
| add_custom_command(TARGET ${target} PRE_BUILD |
| COMMAND ${CMAKE_COMMAND} -E make_directory ${new_folder} |
| COMMAND ln -sf ${root}/${file} ${new_filename} |
| COMMENT "Creating symlink ${new_filename} -> ${root}/${file}" |
| WORKING_DIRECTORY ${root} VERBATIM) |
| endif() |
| endforeach() |
| endfunction() |
|
|
| ################################################################################################ |
| # Gather docs from examples/*.ipynb and add YAML front-matter. |
| function(gather_notebooks_as_prebuild_cmd target gathered_dir root) |
| set(full_gathered_dir ${root}/${gathered_dir}) |
|
|
| if(NOT PYTHON_EXECUTABLE) |
| message(STATUS "Python interpeter is not found. Can't include *.ipynb files in docs. Skipping...") |
| return() |
| endif() |
|
|
| file(GLOB_RECURSE notebooks ${root}/examples/*.ipynb) |
| foreach(file ${notebooks}) |
| file(RELATIVE_PATH file ${root} ${file}) |
| set(new_filename ${full_gathered_dir}/${file}) |
|
|
| get_filename_component(new_folder ${new_filename} PATH) |
| add_custom_command(TARGET ${target} PRE_BUILD |
| COMMAND ${CMAKE_COMMAND} -E make_directory ${new_folder} |
| COMMAND ${PYTHON_EXECUTABLE} scripts/copy_notebook.py ${file} ${new_filename} |
| COMMENT "Copying notebook ${file} to ${new_filename}" |
| WORKING_DIRECTORY ${root} VERBATIM) |
| endforeach() |
|
|
| set(${outputs_var} ${outputs} PARENT_SCOPE) |
| endfunction() |
|
|
| ################################################################################################ |
| ########################## [ Non macro part ] ################################################## |
|
|
| # Gathering is done at each 'make doc' |
| file(REMOVE_RECURSE ${PROJECT_SOURCE_DIR}/docs/gathered) |
|
|
| # Doxygen config file path |
| set(DOXYGEN_config_file ${PROJECT_SOURCE_DIR}/.Doxyfile CACHE FILEPATH "Doxygen config file") |
|
|
| # Adding docs target |
| add_custom_target(docs COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_config_file} |
| WORKING_DIRECTORY ${PROJECT_SOURCE_DIR} |
| COMMENT "Launching doxygen..." VERBATIM) |
|
|
| # Gathering examples into docs subfolder |
| gather_notebooks_as_prebuild_cmd(docs docs/gathered ${PROJECT_SOURCE_DIR}) |
| gather_readmes_as_prebuild_cmd(docs docs/gathered ${PROJECT_SOURCE_DIR}) |
|
|
| # Auto detect output directory |
| file(STRINGS ${DOXYGEN_config_file} config_line REGEX "OUTPUT_DIRECTORY[ \t]+=[^=].*") |
| if(config_line) |
| string(REGEX MATCH "OUTPUT_DIRECTORY[ \t]+=([^=].*)" __ver_check "${config_line}") |
| string(STRIP ${CMAKE_MATCH_1} output_dir) |
| message(STATUS "Detected Doxygen OUTPUT_DIRECTORY: ${output_dir}") |
| else() |
| set(output_dir ./doxygen/) |
| message(STATUS "Can't find OUTPUT_DIRECTORY in doxygen config file. Try to use default: ${output_dir}") |
| endif() |
|
|
| if(NOT IS_ABSOLUTE ${output_dir}) |
| set(output_dir ${PROJECT_SOURCE_DIR}/${output_dir}) |
| get_filename_component(output_dir ${output_dir} ABSOLUTE) |
| endif() |
|
|
| # creates symlink in docs subfolder to code documentation built by doxygen |
| add_custom_command(TARGET docs POST_BUILD VERBATIM |
| COMMAND ln -sfn "${output_dir}/html" doxygen |
| WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}/docs |
| COMMENT "Creating symlink ${PROJECT_SOURCE_DIR}/docs/doxygen -> ${output_dir}/html") |
|
|
| # for quick launch of jekyll |
| add_custom_target(jekyll COMMAND jekyll serve -w -s . -d _site --port=4000 |
| WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}/docs |
| COMMENT "Launching jekyll..." VERBATIM) |
|
|
