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