add documentation workflow etc

.github/workflows/docs.yml

@@ -0,0 +1,39 @@
+
+name: Build Docs
+on:
+    push:
+      branches: [ "master" ]
+    pull_request:
+
+jobs: 
+  build-and-deploy-docs: 
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install Doxygen and some other things
+      shell: bash
+      run: sudo apt-get update && sudo apt-get install -y doxygen && sudo apt-get install -y graphviz
+
+    - name: Set reusable strings
+      # Turn repeated input strings (such as the build output directory) into step outputs. These step outputs can be used throughout the workflow file.
+      id: strings
+      shell: bash
+      run: |
+        echo "build-output-dir=${{ github.workspace }}/build" >> "$GITHUB_OUTPUT"
+
+    - name: Configure ADOL-C
+      run: 
+        cmake -B ${{ steps.strings.outputs.build-output-dir }} -S ${{ github.workspace }}
+
+    - name: build docs
+      run:
+        cmake --build ${{ steps.strings.outputs.build-output-dir }} --target doxygen 
+
+
+    - name: Deploy
+      uses: peaceiris/actions-gh-pages@v4
+      with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ${{ steps.strings.outputs.build-output-dir }}/ADOL-C/doc/doxygen/html

ADOL-C/doc/doxygen/CMakeLists.txt

@@ -2,8 +2,10 @@ find_package(Doxygen)
 
 if(DOXYGEN_FOUND)
 
-  set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
-  set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+  # Absolute path to manual in the source tree:
+  set(PDF_SOURCE_PATH ${CMAKE_SOURCE_DIR}/ADOL-C/doc/adolc-manual.pdf)
+  set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/doxyfile.in)
+  set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/doxyfile)
   configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
 
   add_custom_target(doxygen

ADOL-C/doc/doxygen/differentiating_cpp_code.md

@@ -0,0 +1,61 @@
+@page differentiating_cpp_code Differentiating C++ Code
+
+## Differentiating C++ Code
+
+ADOL-C utilizes C++'s operator overloading features to compute derivatives of programs. This operator overloading is applied via ADOL-C's main datatype `adouble`. Basic derivative evaluation can be done using tape-based or tape-less AD.
+
+The tape-based AD utilizes a tape to store intermediate values to be later used to compute, e.g., a gradient using reverse mode AD or many of the derivative drivers. In contrast, the tape-less `adouble` is only capable of forward-mode computations, but serves as a light-weight option, which can be much faster in some situations.
+
+---
+
+## Tape-based AD
+
+To compute derivatives using tape-based AD, all necessary operations must be included in a [`trace_on`](@ref trace_on) – [`trace_off`](@ref trace_off) block.
+
+Inside this block, all operations involving `adouble` variables are traced onto the tape.
+
+> 💡 **Best practice**: allocate and free all `adouble` objects within the same [`trace_on`](@ref trace_on) – [`trace_off`](@ref trace_off) block.
+
+---
+
+## Tape-less AD
+
+In comparison, for tape-less AD ...
+
+*(To be completed similarly)*
+
+---
+
+## Troubleshooting
+
+### `adouble` variables outside [`trace_on`](@ref trace_on) – [`trace_off`](@ref trace_off) block
+
+It is possible (though not recommended) to have `adouble` variables outside the tracing block. To do so, you must explicitly create a tape using [`createNewTape`](@ref createNewTape) and select it using [`setCurrentTape`](@ref setCurrentTape) **before** allocating any `adouble` on this specific tape.
+
+> ⚠️ When working with multiple tapes, be careful during deallocation:
+> `adouble` objects notify their associated tape via [`currentTape`](@ref currentTape) during destruction. If the wrong tape is selected, this may result in undefined behavior or errors.
+
+However, it is always safe to encapsulate logic like this:
+
+```cpp
+const short tapeId = createNewTape();
+call_your_function(tapeId);
+gradient(tapeId, ...);
+```
+
+with
+
+```cpp
+void call_your_function(short tapeId) {
+    setCurrentTape(tapeId);
+
+    // Allocate your data here
+    std::array<adouble, 10> data;
+
+    trace_on(tapeId);
+
+    // Computations involving `adouble`
+
+    trace_off();
+}
+```

ADOL-C/doc/doxygen/Doxyfile.in → ADOL-C/doc/doxygen/doxyfile.in

@@ -342,7 +342,7 @@ OPTIMIZE_OUTPUT_SLICE  = NO
 #
 # Note see also the list of default file extension mappings.
 
-EXTENSION_MAPPING      =
+EXTENSION_MAPPING      = md=markdown 
 
 # If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments
 # according to the Markdown format, which allows for more readable
@@ -944,8 +944,10 @@ WARN_LOGFILE           =
 # Note: If this tag is empty the current directory is searched.
 
 INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/../../include/adolc/ \
-                         @CMAKE_CURRENT_SOURCE_DIR@/Mainpage.md \
-                         @CMAKE_CURRENT_SOURCE_DIR@/Topics.md
+                         @CMAKE_CURRENT_SOURCE_DIR@/mainpage.md \
+                         @CMAKE_CURRENT_SOURCE_DIR@/topics.md \
+                         @CMAKE_CURRENT_SOURCE_DIR@/drivers.md \
+                         @CMAKE_CURRENT_SOURCE_DIR@/differentiating_cpp_code.md 
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1160,7 +1162,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE = Mainpage.md
+USE_MDFILE_AS_MAINPAGE = mainpage.md
 #USE_MDFILE_AS_MAINPAGE = ../README.md
 
 # The Fortran standard specifies that for fixed formatted Fortran code all
@@ -1410,7 +1412,7 @@ HTML_EXTRA_STYLESHEET  =
 # files will be copied as-is; there are no commands or markers available.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_EXTRA_FILES       =
+HTML_EXTRA_FILES       =  @PDF_SOURCE_PATH@ 
 
 # The HTML_COLORSTYLE tag can be used to specify if the generated HTML output
 # should be rendered with a dark or light theme.
@@ -2864,3 +2866,4 @@ MSCGEN_TOOL            =
 # command).
 
 MSCFILE_DIRS           =
+

ADOL-C/doc/doxygen/drivers.md

@@ -0,0 +1,3 @@
+@page drivers Drivers
+
+## Drivers

ADOL-C/doc/doxygen/mainpage.md

@@ -0,0 +1,58 @@
+# ADOL-C: A Package for the Automatic Differentiation of Algorithms Written in C/C++
+
+@warning This documentation is experimental. We have not yet transferred the documentation to this place.
+
+See the [comprehensive manual](adolc-manual.pdf)
+
+## Scope of the library
+
+The C++ package ADOL-C described here facilitates the evaluation of
+first and higher derivatives of vector functions that are defined
+by computer programs written in C++. 
+
+ADOL-C provides drivers to compute Jacobians, Hessians, univariate Taylor Coefficients or derivative tensors of arbitrary order. There are drivers for Jacobian-vector or Jacobian-matrix-products and vector-Jacobian or matrix-Jacobian products. Sparsity is also supported for first and second-order derivatives. For solution curves defined by ordinary differential equations,
+special routines are provided that evaluate the Taylor coefficient vectors and their Jacobians with respect to the current state vector.
+There are many more drivers like drivers for implicitly defined functions or drivers for fixed-point iterations. For a full list please refer to [this](@ref drivers) page
+
+## Documentation
+
+
+### Class documentation
+
+The library contains a class documentation generated by using [doxygen].
+In order to generate it, it is required that the `doxygen` program
+is available and found by CMake. After the project was configured using
+CMake and if doxygen was found, the documentation can
+be build by calling
+```shell
+make doxygen
+```
+from within the build directory. The entry page of the documentation is located
+in `ADOL-C/doc/doxygen/html/index.html` within the build directory.
+For an overview of the contained features and submodules
+you can e.g. refer to the [Topics](topics.html) section of the doxygen documentation.
+
+
+
+
+
+### Examples
+
+@todo Describe where to find examples.
+
+
+
+## Using ADOL-C and licensing
+
+@todo How to incorporate ADOL-C in user code.
+@todo How to cite ADOL-C
+@todo Licence
+
+
+
+## Building ADOL-C
+
+### Dependencies
+### Building the library
+
+[doxygen]: http://www.stack.nl/~dimitri/doxygen/

ADOL-C/doc/doxygen/tape_interface.dox

@@ -0,0 +1,10 @@
+/**
+ * \page tape_interface Tape Interface
+ *
+ * # Tape Interface
+ *
+ * This page documents all tape lifecycle functions from `tape_interface.h`.
+ * These are grouped in the \ref tape_group.
+ *
+ * \see \ref tape_group for full function documentation.
+ */

ADOL-C/doc/doxygen/Topics.md → ADOL-C/doc/doxygen/topics.md

@@ -6,4 +6,3 @@
 
 @defgroup TapeBackward Tape-based backward mode
 @brief Interfaces for tape-base backward mode AD
-

ADOL-C/include/adolc/tape_interface.h

@@ -9,6 +9,10 @@
 #include <memory>
 #include <vector>
 
+/// \defgroup tape_group Tape Interface
+/// \brief Functions for controlling the AD tape lifecycle
+/// \{
+
 /**
  * @brief Returns a thread-local vector that holds unique pointers to ValueTape
  * instances.
@@ -18,6 +22,7 @@
  * management.
  *
  * @return Reference to the thread-local vector of unique pointers to ValueTape.
+ * @ingroup tape_group
  */
 inline std::vector<std::unique_ptr<ValueTape>> &tapeBuffer() {
   thread_local std::vector<std::unique_ptr<ValueTape>> tBuffer;
@@ -317,4 +322,5 @@ ADOLC_API void setTapeInfoHessSparse(short tapeId, SparseHessInfos sHInfos) {
 }
 #endif
 
+/// \}
 #endif // ADOLC_TAPE_INTERFACE_H

README.md

@@ -2,6 +2,7 @@
 
 [![Build Status](https://github.com/coin-or/ADOL-C/actions/workflows/ci.yml/badge.svg)](https://github.com/coin-or/ADOL-C/actions?query=branch%3Amaster)
 [![codecov](https://codecov.io/github/coin-or/ADOL-C/graph/badge.svg?token=4FSN87ZXCZ)](https://codecov.io/github/coin-or/ADOL-C)
+[![Docs](https://img.shields.io/badge/docs-stable-blue.svg)](https://coin-or.github.io/ADOL-C/)
 
 > [!WARNING]  
 > We are in the process of modernizing ADOL-C. The master branch is unstable. Please use the latest release or help us by reporting bugs.