Add an Examples section and the 2.0.3 to 2.1.1 changelog

doc/CMakeLists.txt

@@ -4,44 +4,60 @@
 
 # Technical API documentation (Doxygen)
 
-  if(WITH_PYTHON)
-
-    find_package(Doxygen)# 1.16.1 QUIET)
+  # Doxygen is looked for whatever WITH_PYTHON is: besides the docstrings of the
+  # binding, its XML output provides the API references of the manual (breathe)
+  # and its HTML output the api/ pages of the manual website.
+  find_package(Doxygen)# 1.16.1 QUIET)
 
-    if(NOT DOXYGEN_FOUND)
+  if(NOT DOXYGEN_FOUND)
 
-      message(STATUS "The required version of Doxygen has not been found, the API documentation will not be generated.")
+    message(STATUS "The required version of Doxygen has not been found, the API documentation will not be generated.")
 
+  else()
+
+    if(NOT DOXYGEN_DIR)
+      message(STATUS "Doxygen ${DOXYGEN_VERSION} found.")
     else()
+      message(STATUS "Doxygen ${DOXYGEN_VERSION} found in ${DOXYGEN_DIR}.")
+    endif()
 
-      if(NOT DOXYGEN_DIR)
-        message(STATUS "Doxygen ${DOXYGEN_VERSION} found.")
-      else()
-        message(STATUS "Doxygen ${DOXYGEN_VERSION} found in ${DOXYGEN_DIR}.")
-      endif()
+    # Includes CMake commands in config file:
+    configure_file(api/Doxyfile.in api/Doxyfile)
 
-      # Includes CMake commands in config file:
-      configure_file(api/Doxyfile.in api/Doxyfile)
+    set(DOXYGEN_INPUT ${CMAKE_CURRENT_BINARY_DIR}/api/Doxyfile)
+    set(DOXYGEN_OUTPUT ${APIDOC_DIR}/html/index.html)
 
-      set(DOXYGEN_INPUT ${CMAKE_CURRENT_BINARY_DIR}/api/Doxyfile)
-      set(DOXYGEN_OUTPUT ${APIDOC_DIR}/html/index.html)
+    if(WIN32)
+      set(NULL_DEST NUL 2>&1)
+    else()
+      set(NULL_DEST "/dev/null")
+    endif()
 
-      if(WIN32)
-        set(NULL_DEST NUL 2>&1)
-      else()
-        set(NULL_DEST "/dev/null")
-      endif()
+    # Only the binding needs the XML output at configure time, python/ turning
+    # it into docstring headers while it is configured. The manual needs it when
+    # it is built, and gets it from the api target, which it depends on.
+    if(WITH_PYTHON)
 
       message(STATUS "Building API Documentation (mandatory for Python binding or for building the manual)")
 
-      set(SPHINX_EXTRA_API ${CMAKE_CURRENT_BINARY_DIR}/manual/extra_html/api)
-      file(MAKE_DIRECTORY ${SPHINX_EXTRA_API})
-
-      execute_process(COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_INPUT} OUTPUT_QUIET)
-      add_custom_target(api COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_INPUT} OUTPUT_QUIET)
+      execute_process(
+        COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_INPUT}
+        OUTPUT_QUIET
+        ERROR_VARIABLE DOXYGEN_ERROR
+        RESULT_VARIABLE DOXYGEN_RESULT
+      )
+      if(NOT DOXYGEN_RESULT EQUAL 0)
+        if(DOXYGEN_RESULT STREQUAL "Segmentation fault" AND EXISTS "${CMAKE_BINARY_DIR}/doc/api/xml/index.xml")
+          message(WARNING "Doxygen exited with '${DOXYGEN_RESULT}' but generated XML output. Continuing so Python docstrings can still be generated.")
+        else()
+          message(FATAL_ERROR "Doxygen failed to generate the API documentation (exit code ${DOXYGEN_RESULT}), which is required for the Python docstrings. Doxygen errors: ${DOXYGEN_ERROR}")
+        endif()
+      endif()
 
     endif()
 
+    add_custom_target(api COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_INPUT} OUTPUT_QUIET)
+
   endif()
 
 # User manual (Sphinx)
@@ -58,17 +74,28 @@
     configure_file(${CMAKE_CURRENT_SOURCE_DIR}/manual/conf.py.in ${CMAKE_CURRENT_BINARY_DIR}/manual/conf.py)
 
     set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR}/manual)
-    set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/manual)
+    # The HTML output (outdir) is kept distinct from, and nested under, the confdir
+    # (${CMAKE_CURRENT_BINARY_DIR}/manual, where conf.py/_static live): otherwise
+    # Sphinx warns that html_static_path sits inside outdir.
+    set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/manual/html)
 
     # Copying _static files of Sphinx to build directories
-    foreach(static_file ${CMAKE_CURRENT_SOURCE_DIR}/manual/_static/)
-      file(COPY ${static_file} DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/manual/_static/)
-    endforeach()
+    if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/manual/_static")
+      execute_process(
+        COMMAND ${CMAKE_COMMAND} -E copy_directory
+          "${CMAKE_CURRENT_SOURCE_DIR}/manual/_static"
+          "${CMAKE_CURRENT_BINARY_DIR}/manual/_static"
+      )
+    endif()
 
     # Copying tmp files
-    foreach(static_file ${CMAKE_CURRENT_SOURCE_DIR}/manual/tmp/)
-      file(COPY ${static_file} DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/manual/tmp/)
-    endforeach()
+    if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/manual/tmp")
+      execute_process(
+        COMMAND ${CMAKE_COMMAND} -E copy_directory
+          "${CMAKE_CURRENT_SOURCE_DIR}/manual/tmp"
+          "${CMAKE_CURRENT_BINARY_DIR}/manual/tmp"
+      )
+    endif()
 
     # todo: the SPHINX_EXECUTABLE is already set by FindSphinx.cmake:
     # check that it works without the following overload for Win and Linux:
@@ -87,19 +114,34 @@
                       WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
                       COMMENT "Generating the manual website using Sphinx")
 
-    add_custom_command(
-      TARGET manual POST_BUILD
-      COMMAND ${CMAKE_COMMAND} -E copy_directory
-              ${CMAKE_BINARY_DIR}/doc/api/html
-              ${SPHINX_EXTRA_API}
-      COMMENT "Copying generated Doxygen HTML to Sphinx extra_html/api"
-    )
-
+    if(TARGET api)
+
+      # Without this dependency, Sphinx would read whatever Doxygen output the
+      # build tree happens to hold: none at all when WITH_PYTHON is off, and the
+      # one of the last configuration otherwise.
+      add_dependencies(manual api)
+
+      add_custom_command(
+        TARGET manual POST_BUILD
+        COMMAND ${CMAKE_COMMAND} -E copy_directory
+                ${CMAKE_BINARY_DIR}/doc/api/html
+                ${SPHINX_BUILD}/api
+        COMMENT "Copying generated Doxygen HTML into the manual output (outdir)/api"
+      )
+
+    else()
+
+      message(STATUS "Doxygen not found, the manual will be generated without its API references.")
+
+    endif()
+
+    # The Doxygen API HTML is already part of ${SPHINX_BUILD}/api (copied there
+    # by the POST_BUILD step above), so installing ${SPHINX_BUILD}/ below is
+    # sufficient -- a separate install of ${CMAKE_CURRENT_BINARY_DIR}/api would
+    # duplicate it under a different, unreferenced layout (api/html/*.html
+    # alongside the Doxyfile, instead of api/*.html).
     install(DIRECTORY ${SPHINX_BUILD}/
             DESTINATION share/codac_website
             OPTIONAL)
-    install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/api
-            DESTINATION share/codac_website
-        OPTIONAL)
 
   endif()

doc/manual/conf.py.in

@@ -108,4 +108,9 @@ breathe_projects = {
 togglebutton_hint = "Reveal the solution."
 togglebutton_hint_hide = "Hide the solution."
 
-html_extra_path = ['extra_html']
+# The generated Doxygen API HTML is copied directly into outdir/api by a
+# POST_BUILD step in doc/CMakeLists.txt (after sphinx-build runs), rather
+# than staged through html_extra_path: since outdir is a distinct directory
+# from confdir, there is no ordering constraint forcing it to exist beforehand,
+# so a direct copy avoids maintaining (and duplicating on disk) an
+# intermediate staging copy that only html_extra_path would ever read.

doc/manual/development/api_redirect.rst

@@ -5,4 +5,4 @@ C++ API
 
 .. raw:: html
 
-    <meta http-equiv="refresh" content="0; url=../extra_html/api/namespacecodac2.html">
+    <meta http-equiv="refresh" content="0; url=../api/namespacecodac2.html">

doc/manual/development/changelog.rst

@@ -3,13 +3,203 @@
 Changelog
 =========
 
-Upcoming version 
+Upcoming version
 ****************
 
+Nothing reported yet since :ref:`version 2.1.1 <sec-dev-changelog-2-1-1>`.
+
+.. _sec-dev-changelog-2-1-1:
+
+Version 2.1.1
+*************
+
+Commit 4c9af64 ([qinter] Invert q-relaxed intersection convention)
+-------------------------------------------------------------------
+
+Meaning of ``q`` in ``CtcQInter`` and ``SepQInter``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**This is a breaking change: existing code keeps compiling, but computes something else.**
+
+The q-relaxed intersection of :math:`n` sets is now parametrized by the number of
+constraints that are allowed to be **violated**, where ``q`` used to be the number
+of constraints that had to be **satisfied**. With :math:`n` sets, a former ``q``
+becomes :math:`n-q`.
+
+.. tabs::
+
+  .. code-tab:: py
+
+    # Three separators, at most one of which may be wrong.
+
+    # Old way: q was the number of sets an element had to belong to
+    # sep = SepQInter(2, s1,s2,s3)
+
+    # New way: q is the number of sets it may be outside of
+    sep = SepQInter(1, s1,s2,s3)
+
+  .. code-tab:: c++
+
+    // Three separators, at most one of which may be wrong.
+
+    // Old way: q was the number of sets an element had to belong to
+    // SepQInter sep(2, s1,s2,s3);
+
+    // New way: q is the number of sets it may be outside of
+    SepQInter sep(1, s1,s2,s3);
+
+The same applies to ``CtcQInter`` and to the ``qinter()`` function.
+
+Commit ff4fe62 ([ctc] added CtcWrapper(Y&& y) constructor)
+-----------------------------------------------------------
+
+``CtcWrapper`` can now be built from a temporary domain, which avoids naming an
+intermediate variable when the wrapped value is built on the spot.
+
+Commit 21c9a3c ([graphics] corrected bug with random colors)
+--------------------------------------------------------------
+
+Bugfix in the generation of random colors.
+
+Commit b134a18 ([ctc] minor improvment in CtcUnion)
+------------------------------------------------------
+
+Internal improvement of ``CtcUnion``, with no change to its interface.
+
+
+Version 2.1.0
+*************
+
+Commit b688eee ([ctc/sep] revised constructors of Ctc/Sep Inter/Union/QInter)
+-------------------------------------------------------------------------------
+
+Building an intersection or a union from several operators
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``CtcInter``, ``CtcUnion``, ``CtcQInter``, ``SepInter``, ``SepUnion`` and
+``SepQInter`` now accept a variadic list of operands as well as an initializer
+list, instead of requiring a collection built beforehand:
+
+.. tabs::
+
+  .. code-tab:: py
+
+    sep = SepInter(s1, s2, s3)      # variadic
+    sep = SepInter([s1, s2, s3])    # or from a list
+
+  .. code-tab:: c++
+
+    SepInter sep(s1, s2, s3);       // variadic
+    SepInter sep({s1, s2, s3});     // or from an initializer list
+
+The former constructors still work, so this addition is backward compatible.
+
+Commit ec5e3d2 ([graphics] save function for Figure2D, closes #377)
+----------------------------------------------------------------------
+
+``Figure2D`` gained a ``save(filename)`` method, which writes the current state
+of the figure to a file. Together with ``clear()``, it is what lets an animation
+export one file per frame; see the ``00_graphics/graphic_animation`` example.
+
+Commit 91a656c ([graphics] solving IPE figure not clearing, closes #383)
+---------------------------------------------------------------------------
+
+Bugfix: ``clear()`` had no effect on the IPE output of a figure.
+
+Commit 3212d3a ([graphics] dot detection for IPE file save)
+--------------------------------------------------------------
+
+The name given to an IPE output is now handled correctly when it already carries
+an extension.
+
+Commits 055ee10, e62d2f3 ([matlab] graphical example and bindings)
+--------------------------------------------------------------------
+
+The drawing functions are now available from MATLAB, with a dedicated graphical
+example (``00_graphics/graphic_examples.m``).
+
+
+Version 2.0.5
+*************
+
+Commit dacd8e7 ([op] corrected bug in several definition domains)
+--------------------------------------------------------------------
+
+Bugfix in the definition domains used for the backward evaluation of several
+operators: ``abs``, ``acos``, ``asin``, ``atan2``, ``log``, ``max``, ``sign``,
+``sqrt``, ``tan`` and the division. Contractions involving these operators could
+remove values that were in fact feasible, so results obtained with an earlier
+version and relying on them are worth recomputing.
+
+
+Version 2.0.4
+*************
+
+Commit 9754d0f ([sep] SepInter and SepUnion can be built from a list of separators)
+-------------------------------------------------------------------------------------
+
+First step of what commit b688eee generalized in version 2.1.0.
+
+
+Version 2.0.3
+*************
+
 Pull Request #379 from godardma (27/04)
 ---------------------------------------
 
 ``Zonotope`` and ``Parallelepiped`` center is now ``c`` instead of ``z`` to avoid ambiguity.
+The same commit added ``operator+`` on ``Zonotope``.
+
+Commits 1860083, 8c7b17e ([ctc] CtcParallelepiped is now CtcWrapper<Parallelepiped>)
+--------------------------------------------------------------------------------------
+
+``CtcParallelepiped`` was introduced and then immediately replaced by the generic
+``CtcWrapper<Parallelepiped>``; use the latter. The same commit added the handling
+of empty ``Zonotope`` objects. See :ref:`sec-ctc-shape-ctcwrapper`.
+
+Commit 82fd8a3 ([sep] added SepPolarCart + binding)
+-----------------------------------------------------
+
+New separator ``SepPolarCart``, the counterpart of ``SepCartPolar``, available in
+C++ and in Python.
+
+Commit 7b6ba3a ([intv] added < and > operators)
+-------------------------------------------------
+
+``Interval`` gained the comparison operators ``<`` and ``>``. They return a
+``BoolInterval`` enclosing the truth value of :math:`t<s` (resp. :math:`t>s`) for
+every :math:`t` of the first interval and every :math:`s` of the second:
+``TRUE`` or ``FALSE`` when the two intervals are separated, ``UNKNOWN`` when they
+overlap, and ``EMPTY`` when either of them is empty. See
+:ref:`sec-intervals-class` and :ref:`sec-intervals-boolinterval-class`.
+
+Commits 710a154, fa00923 (Bugfix for IntvFullPivLU::solve)
+-------------------------------------------------------------
+
+``IntvFullPivLU::solve`` gave a wrong result when called with rectangular
+matrices (more rows than columns). See :ref:`sec-linear-lu`.
+
+Commit f815210 ([graphics] possibility to choose origin for axes)
+--------------------------------------------------------------------
+
+``Figure3D::draw_axes`` takes a second argument, the origin of the axes, which
+defaults to the previous behaviour:
+
+.. tabs::
+
+  .. code-tab:: py
+
+    fig.draw_axes(1.0, [1,2,3])   # size, then origin
+
+  .. code-tab:: c++
+
+    fig.draw_axes(1.0, {1,2,3});  // size, then origin
+
+Commit 312cd79 ([doc] doc for multi-thread)
+----------------------------------------------
+
+Documentation of the threading facilities: see :ref:`sec-tools-threading`.
+
 
 Version 2.0.2
 *************