master: cmake include_doc option.

CMakeLists.txt

@@ -373,6 +373,56 @@ ELSE( )
    # cppad_has_cppadcg
    SET(cppad_has_cppadcg 0)
 ENDIF( include_cppadcg )
+#
+# package = xrst
+SET( include_doc FALSE CACHE BOOL "include documentation")
+IF( include_doc )
+   #
+   # xrst_path
+   FIND_PROGRAM( xrst_path xrst )
+   IF( "${xrst_path}" STREQUAL "xrst_path-NOTFOUND" )
+      MESSAGE(FATAL_ERROR
+         "include_doc is true and cannot find xrst in system path"
+      )
+   ENDIF( )
+   #
+   # processor_count
+   INCLUDE(ProcessorCount)
+   ProcessorCount(processor_count)
+   IF( processor_count EQUAL 0 )
+      SET(processor_count 1)
+   ENDIF( )
+   #
+   # see
+   # https://discourse.cmake.org/t/how-to-install-a-generated-directory/1267
+   #
+   # doc_dir
+   SET(doc_dir "${CMAKE_SOURCE_DIR}/build/html")
+   #
+   # doc_user
+   ADD_CUSTOM_TARGET(doc_user ALL
+      COMMAND xrst
+         --group_list default app
+         --local_toc
+         --html_theme sphinx_rtd_theme
+         --number_jobs ${processor_count}
+         --index_page_name user_guide
+         --suppress_spell_warnings
+         --config_file "${CMAKE_SOURCE_DIR}/xrst.toml"
+   )
+   #
+   # doc_dev
+   ADD_CUSTOM_TARGET(doc_dev
+      COMMAND xrst
+         --group_list default app dev
+         --local_toc
+         --html_theme sphinx_rtd_theme
+         --number_jobs ${processor_count}
+         --index_page_name user_guide
+         --suppress_spell_warnings
+         --config_file "${CMAKE_SOURCE_DIR}/xrst.toml"
+   )
+ENDIF( include_doc )
 # =============================================================================
 # cppad_lib
 # Perhaps in the future cppad_lib will depend on cmake header only flag ?
@@ -590,17 +640,12 @@ INSTALL(
 )
 #
 # During install copy doc direcrory to cppad_abs_docdir/cppad
-IF ( cmake_install_docdir )
-   # ADD_CUSTOM_TARGET(docdir COMMAND
-   #    xrst
-   #    --group_list default app
-   #    --config_file "${CMAKE_CURRENT_SOURCE_DIR}/xrst.toml"
-   # )
+IF ( cmake_install_docdir AND include_doc )
    INSTALL(
-      DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/build/html/"
+      DIRECTORY "${CMAKE_SOURCE_DIR}/build/html/"
       DESTINATION ${cppad_abs_docdir}/cppad
    )
-ENDIF ( cmake_install_docdir )
+ENDIF ( cmake_install_docdir AND include_doc )
 
 # =============================================================================
 # uninstall procedure

appendix/whats_new/2024.xrst

@@ -26,6 +26,7 @@
    xcode
    yy
    yyyy
+   dev
 }
 
 Release Notes for 2024
@@ -34,6 +35,17 @@ Release Notes for 2024
 mm-dd
 *****
 
+12-09
+=====
+#. An option to build a local copy of the user or developer documentation
+   was added to the install procedure; see :ref:`cmake@include_doc` .
+   This also affects the :ref:`cmake@cmake_install_docdir` option.
+
+#. The developer documentation for the variable operators and sweep functions
+   was improved (and the corresponding source code was simplified); see
+   op_code_var.html and dev_sweep.html in the developer documentation.
+
+
 11-23
 =====
 In the :ref:`atomic_four_norm_sq.cpp-name` example,
@@ -52,7 +64,7 @@ improve the comment about the relation between G and H; to be specific::
 11-19
 =====
 Fix the :ref:`configure@--with-clang` and :ref:`configure@--with-verbose-make`
-options did not have any effect in the configure script. 
+options did not have any effect in the configure script.
 This has been fixed.
 
 11-16

bin/run_cmake.sh

@@ -259,6 +259,7 @@ fi
 if [ -d '/usr/share' ] && [ "$yes_documentation" == 'yes' ]
 then
    cmake_args="$cmake_args -D cmake_install_docdir=share/doc"
+   cmake_args="$cmake_args -D include_doc=true"
 fi
 #
 # cmake_install_libdirs

xrst/install/cmake.xrst

@@ -38,9 +38,9 @@
    vcvarsall
    wno
    wshadow
-   xml
    yyyy
    yyyymmdd
+   dev
 }
 
 Using CMake to Configure CppAD
@@ -122,6 +122,7 @@ The full version of the command, with all its optional arguments is:
 | |tab| \\
 | |tab| ``-D cmake_defined_ok`` = *cmake_defined_ok*                        \\
 | |tab| \\
+| |tab| ``-D include_doc`` = *true_or_false*                              \\
 | |tab| ``-D include_adolc`` = *true_or_false*                              \\
 | |tab| ``-D include_ipopt`` = *true_or_false*                              \\
 | |tab| ``-D include_cppadcg`` = *true_or_false*                            \\
@@ -365,17 +366,18 @@ The default value for *cmake_install_datadir* is ``share`` .
 cmake_install_docdir
 ********************
 This is the middle level relative path below which
-the CppAD documentation files are installed.
+the CppAD user documentation files are installed.
 For example,
 if *cppad_prefix* is ``/usr`` ,
 *cmake_install_docdir* is ``share/doc`` , and
 *cppad_postfix* is not specified,
-the file ``cppad.xml`` is installed in the location
+the file ``user_guide.html`` is installed in the location
 
-   / ``usr/share/doc/cppad/cppad.xml``
+   / ``usr/share/doc/cppad/user_guide.html``
 
-There is no default value for *cmake_install_docdir* .
-If it is not specified, the documentation files are not installed.
+If *cmake_install_docdir* is not specified,
+or :ref:`cmake@include_doc` is false,
+the documentation files are not installed.
 
 cmake_defined_ok
 ****************
@@ -385,6 +387,19 @@ If it is false, some checks will be made to make sure
 certain variables are not defined twice.
 The default value for *cmake_defined_ok* is true.
 
+include_doc
+***********
+If ``include_doc=true`` is in the command line, the
+`xrst <https://xrst.readthedocs.io/latest/>`_
+program must be installed.
+In this case, the user and developer documentation targets
+``doc_user`` and ``doc_dev`` will be available.
+For example, if the :ref:`cmake@generator` is ``Ninja``
+the commands ``ninja doc_user`` and ``ninja doc_dev``
+will build the  corresponding documentation in the
+``build/html`` sub-directory of the
+:ref:`download@Distribution Directory` .
+
 include_adolc
 *************
 The :ref:`adolc-name` examples