cmake/SalomeDocumentationMacros.cmake

   1 # Copyright (C) 2013-2024  CEA, EDF, OPEN CASCADE
   2 #
   3 # This library is free software; you can redistribute it and/or
   4 # modify it under the terms of the GNU Lesser General Public
   5 # License as published by the Free Software Foundation; either
   6 # version 2.1 of the License, or (at your option) any later version.
   7 #
   8 # This library 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 GNU
  11 # Lesser General Public License for more details.
  12 #
  13 # You should have received a copy of the GNU Lesser General Public
  14 # License along with this library; if not, write to the Free Software
  15 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  16 #
  17 # See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
  18 #
  19 # Author: Roman NIKOLAEV
  20 #
  21
  22 #----------------------------------------------------------------------------
  23 # SALOME_ADD_SPHINX_DOC is a macro useful for generating sphinx documentation
  24 #
  25 # USAGE: SALOME_ADD_SPHINX_DOC(sphinx_type sphinx_name src_dir cfg_dir)
  26 #
  27 # ARGUMENTS:
  28 #
  29 # sphinx_type: IN - type of the sphinx generator, use one of the following  types:
  30 #
  31 #                       html       - to make standalone HTML files
  32 #                       dirhtml    - to make HTML files named index.html in directories
  33 #                       singlehtml - to make a single large HTML file
  34 #                       pickle     - to make pickle files
  35 #                       json       - to make JSON files
  36 #                       htmlhelp   - to make HTML files and a HTML help project
  37 #                       qthelp     - to make HTML files and a qthelp project"
  38 #                       devhelp    to make HTML files and a Devhelp project"
  39 #                       epub       to make an epub"
  40 #                       latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
  41 #                       latexpdf   to make LaTeX files and run them through pdflatex"
  42 #                       text       to make text files"
  43 #                       man        to make manual pages"
  44 #                       texinfo    to make Texinfo files"
  45 #                       info       to make Texinfo files and run them through makeinfo
  46 #                       gettext    to make PO message catalogs"
  47 #                       changes    to make an overview of all changed/added/deprecated items
  48 #                       linkcheck  to check all external links for integrity"
  49 #                       doctest    to run all doctests embedded in the documentation (if enabled)\
  50 #
  51 # sphinx_name: IN - documentation target name
  52 #
  53 # src_dir : IN - path to directory that contains the sphinx source files
  54 #
  55 # cfg_dir : IN - path to directory that contains sphinx configuration file (if not specified,
  56 #           it is considered equal to src_dir)
  57 #
  58 # ADDITIONAL OPTIONS:
  59 #
  60 #       OPTIONS   - extra options for sphinx-build
  61 #       PAPER     - LaTeX paper type ("a4" by default)
  62 #       BUILDDIR  - build directory ("_build" by default)
  63 #       OUTDIR    - output directory (by default, set to `sphinx_type` parameter)
  64 #
  65 #----------------------------------------------------------------------------
  66
  67 MACRO(SALOME_ADD_SPHINX_DOC sphinx_type sphinx_name src_dir cfg_dir)
  68   # Parse options
  69   CMAKE_PARSE_ARGUMENTS(SALOME_ADD_SPHINX_DOC "" "PAPER;BUILDDIR;OUTDIR" "OPTIONS" ${ARGN})
  70
  71   # Get type and additional settings
  72   SET(SPHINX_TYPE ${sphinx_type})
  73   IF(${SPHINX_TYPE} STREQUAL "")
  74     SET(SPHINX_TYPE html)
  75   ENDIF(${SPHINX_TYPE} STREQUAL "")
  76
  77   IF("${SALOME_ADD_SPHINX_DOC_PAPER}" STREQUAL "")
  78     SET(SALOME_ADD_SPHINX_DOC_PAPER a4)
  79   ENDIF()
  80
  81   IF("${SALOME_ADD_SPHINX_DOC_BUILDDIR}" STREQUAL "")
  82     SET(SALOME_ADD_SPHINX_DOC_BUILDDIR _build)
  83   ENDIF()
  84
  85   IF("${SALOME_ADD_SPHINX_DOC_OUTDIR}" STREQUAL "")
  86     SET(SALOME_ADD_SPHINX_DOC_OUTDIR ${SPHINX_TYPE})
  87   ENDIF()
  88
  89   SET(SPHINX_CFG ${cfg_dir})
  90   IF("${SPHINX_CFG}" STREQUAL "")
  91     SET(SPHINX_CFG ${src_dir})
  92   ENDIF()
  93
  94   # Initialize internal variables
  95   SET(PAPEROPT_a4 -D latex_paper_size=a4)
  96   SET(PAPEROPT_letter -D latex_paper_size=letter)
  97   SET(ALLSPHINXOPTS  -d ${SALOME_ADD_SPHINX_DOC_BUILDDIR}/doctrees ${PAPEROPT_${SALOME_ADD_SPHINX_DOC_PAPER}} ${SPHINXOPTS})
  98   SET(I18NSPHINXOPTS  ${PAPEROPT_${SALOME_ADD_SPHINX_DOC_PAPER}} ${SPHINXOPTS})
  99
 100   SET(ALLSPHINXOPTS ${ALLSPHINXOPTS} ${src_dir})
 101   SET(I18NSPHINXOPTS ${I18NSPHINXOPTS} ${src_dir})
 102
 103   # Set internal out directory
 104   IF(${SPHINX_TYPE} STREQUAL "gettext")
 105     SET(ALLSPHINXOPTS ${I18NSPHINXOPTS})
 106   ENDIF(${SPHINX_TYPE} STREQUAL "gettext")
 107
 108   # Build sphinx command
 109   SET(_CMD_OPTIONS -b ${SPHINX_TYPE} -c ${SPHINX_CFG} ${ALLSPHINXOPTS} ${SALOME_ADD_SPHINX_DOC_BUILDDIR}/${SALOME_ADD_SPHINX_DOC_OUTDIR})
 110
 111   # This macro mainly prepares the environment in which sphinx should run:
 112   # this sets the PYTHONPATH and LD_LIBRARY_PATH to include OMNIORB, DOCUTILS, SETUPTOOLS, etc ...
 113   SALOME_GENERATE_ENVIRONMENT_SCRIPT(_cmd env_script "${SPHINX_EXECUTABLE}" "${_CMD_OPTIONS}")
 114   ADD_CUSTOM_TARGET(${sphinx_name} ALL ${_cmd})
 115
 116 ENDMACRO(SALOME_ADD_SPHINX_DOC)