.. _dune_cmake_sphinx_doc:

dune_cmake_sphinx_doc
=====================

.. cmake_function:: dune_cmake_sphinx_doc

   .. cmake_brief::

      Generate the documentation that you are just browsing!!!

   .. cmake_param:: BUILDTYPE
      :multi:

      Set the type of build that is requested. By default, "html" is chosen.
      The list of available build types:

      * `html`

   .. cmake_param:: SPHINX_CONF
      :single:
      :argname: conf

      A template for a conf file to be passed to :code:`sphinx-build`.
      The real configuration file will be generated through CMakes
      :code:`configure_file` mechanism. A reasonable default file is
      provided by dune-common. Only use this if you want to create
      custom documentation.

   .. cmake_param:: RST_SOURCES
      :multi:
      :argname: src

      A list of rst sources, that should be configured into the build tree
      (using :code:`configure_file`). If omitted, this defaults to
      :code:`index.rst` and :code:`contents.rst` with suitable content.
      Only use this if you want to create custom documentation.

   .. cmake_param:: MODULE_ONLY
      :option:

      Only document CMake functionality from the current Dune module.

   Generate a documentation for the CMake API. A set of cmake
   modules defined by the parameters and all functions and macros
   there in are automatically generated. The top level directory
   of the documentation is the current build directory (aka the
   directory that this function is called from)

   There are some assumptions on how the documentation in
   the CMake modules is written:

   * At the beginning of each CMake module there is a comment block that is written in restructured text.
     The first two characters of each line (the comment character
     and a blank) are ignored. Any resulting content of lines most form valid rst.
   * TODO document more

