| # 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) | |