1# 2# Siconos is a program dedicated to modeling, simulation and control 3# of non smooth dynamical systems. 4# Siconos is a free software; you can redistribute it and/or modify 5# it under the terms of the GNU Lesser General Public License as published by 6# the Free Software Foundation; either version 2 of the License, or 7# (at your option) any later version. 8# Siconos is distributed in the hope that it will be useful, 9# but WITHOUT ANY WARRANTY; without even the implied warranty of 10# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 11# GNU Lesser General Public License for more details. 12# 13# You should have received a copy of the GNU Lesser General Public License 14# along with Siconos; if not, write to the Free Software 15# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 16# 17# Contact: Vincent ACARY, siconos-team@lists.gforge.inria.fr 18 19#[=======================================================================[.rst: 20doxy2swig_docstrings 21 22Build targets to generate python 23docstrings from xml doxygen output. 24 251) Doxygen to create xml outputs. 262) Doxy2swig to 27 create docstrings from xml outputs. 28 29This macro must be called for each 30component, in LibraryProjectSetup. 31 32-- Targets : 331) headers --> xml using doxygen 342) xml files --> .i using doxy2swig (one .i for each xml file) 353) .i files --> ${COMP}-docstrings.i (one single file) 36 371 : target ${COMP}_xml4swig 382 and 3 : target ${COMP}_docstrings 39 40Note FP : the whole process must be re-executed for any change in a header file of the component 41(unless we set a doxygen conf for each header, don't think we need to bother with that.) 42 43Doxygen steps are driven by cmake while doxy2swig and related are hidden in build_docstrings python 44script. 45#]=======================================================================] 46macro(doxy2swig_docstrings COMP) 47 if(WITH_${COMP}_DOXY2SWIG) 48 49 # -- doxygen/xml config -- 50 51 # 1 - Create COMPdoxy.config.xml in binary dir, 52 # from doxy.config (source dir), taking 53 # into account sources/headers files 54 # of current component COMP. 55 # 56 # 2 - Run doxygen to build xml documentation 57 # 58 # Results in CMAKE_BINARY_DIR/docs/build/xml-docstrings 59 # 60 # Warning : output path must be different from 61 # output for xml used by sphinx/breathe/exhale. 62 # ----------------------------------------------------- 63 64 # Path where xml files will be generated by doxygen as inputs for swig. 65 set(DOXY2SWIG_OUTPUT ${DOXYGEN_OUTPUT}/doxy2swig-xml/${COMP}) 66 file(MAKE_DIRECTORY ${DOXY2SWIG_OUTPUT}) 67 68 # Set doxygen config file name 69 set(DOXY_CONFIG_XML "${CMAKE_BINARY_DIR}/docs/config/${COMP}doxy2swig-xml.config") 70 # Create doxygen configuration file in binary dir 71 set(DOXYGEN_INPUTS ${${COMP}_DOXYGEN_INPUTS}) # list of inputs 72 set(DOXY_QUIET "YES") 73 set(DOXY_WARNINGS "NO") 74 set(GENERATE_HTML NO) 75 set(GENERATE_XML YES) 76 set(EXTRACT_ALL NO) 77 set(EXTRACT_PRIVATE NO) 78 set(XML_OUTPUT doxy2swig-xml/${COMP}) 79 message(" -- Create doxygen conf (xml for docstrings) for component ${COMP}") 80 configure_file(${CMAKE_SOURCE_DIR}/docs/config/doxy2swig.config.in ${DOXY_CONFIG_XML} @ONLY) 81 82 # -- target to generate xml files (doxygen) from current component source files -- 83 # 84 add_custom_target(${COMP}_xml4swig 85 COMMAND ${DOXYGEN_EXECUTABLE} ${DOXY_CONFIG_XML} 86 OUTPUT_FILE ${DOXYGEN_OUTPUT}/${COMP}doxy.log ERROR_FILE ${DOXYGEN_OUTPUT}/${COMP}doxy.log 87 COMMENT " -- Build xml (for swig) doc for component ${COMP} ..." 88 ) 89 90 # -- command to build .i files from xml (doxygen outputs) for current component -- 91 # Call a python function from gendoctools (build_docstrings). 92 add_custom_command(OUTPUT ${SICONOS_SWIG_ROOT_DIR}/${COMP}-docstrings.i 93 DEPENDS ${COMP}_xml4swig 94 COMMAND ${CMAKE_COMMAND} -E env PYTHONPATH=${CMAKE_BINARY_DIR}/share ${PYTHON_EXECUTABLE} -c 95 "from gendoctools.python2rst import build_docstrings as f; f('${${COMP}_HDRS}', '${COMP}', '${DOXY_CONFIG_XML}', '${SICONOS_SWIG_ROOT_DIR}')" 96 VERBATIM 97 ) 98 add_custom_target(${COMP}_docstrings DEPENDS ${SICONOS_SWIG_ROOT_DIR}/${COMP}-docstrings.i 99 COMMENT "Create swig files from xml for component ${COMP}.") 100 else() 101 # No doxy2swig but 102 # generate empty ${COMP}-docstrings.i file (required because of %include in swig files) 103 add_custom_command(OUTPUT ${SICONOS_SWIG_ROOT_DIR}/${COMP}-docstrings.i 104 COMMAND ${CMAKE_COMMAND} -E touch 105 ARGS ${SICONOS_SWIG_ROOT_DIR}/${COMP}-docstrings.i 106 ) 107 add_custom_target(${COMP}_docstrings DEPENDS ${SICONOS_SWIG_ROOT_DIR}/${COMP}-docstrings.i 108 COMMENT "This target has no real effect since swig/docstrings is not activated (PYTHON_WRAPPER and/or DOXY2SWIG is OFF).") 109 110 endif() 111 112 113endmacro() 114 115