[Docs] add CMake API reference

kul-optec · Dec 17, 2023 · c3dbeb2 · c3dbeb2
1 parent 4c5cbad
commit c3dbeb2
Show file tree

Hide file tree

Showing 5 changed files with 57 additions and 20 deletions.
diff --git a/doxygen/requirements.txt b/doxygen/requirements.txt
@@ -2,5 +2,6 @@ breathe @ git+https://github.com/tttapa/breathe@main
 sphinx @ git+https://github.com/tttapa/sphinx@master
 sphinx-tabs~=3.4.4
 sphinxcontrib-matlabdomain~=0.20.2
+sphinxcontrib-moderncmakedomain~=3.27.0
 furo==2023.08.19
 matplotlib
diff --git a/doxygen/sphinx/source/conf.py b/doxygen/sphinx/source/conf.py
@@ -46,6 +46,7 @@
     'matplotlib.sphinxext.plot_directive',
     'sphinxcontrib.matlab',
     'sphinx_tabs.tabs',
+    'sphinxcontrib.moderncmakedomain',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

diff --git a/doxygen/sphinx/source/index.rst b/doxygen/sphinx/source/index.rst
@@ -49,6 +49,7 @@ be found in the `Doxygen pages <../Doxygen/index.html>`_.
    examples/index.rst
    reference/python-api.rst
    reference/cpp-api.rst
+   reference/cmake-api.rst
    reference/matlab-api.rst
    contribution/*
    changelog

diff --git a/doxygen/sphinx/source/reference/cmake-api.rst b/doxygen/sphinx/source/reference/cmake-api.rst
@@ -0,0 +1,52 @@
+CMake API Reference
+===================
+
+To include alpaqa in your CMake project, use the ``find_package`` command:
+
+.. code-block:: cmake
+
+    find_package(alpaqa 1.0.0 [EXACT] [QUIET] [REQUIRED]
+                 [COMPONENTS <components> ...]
+                 [OPTIONAL_COMPONENTS <components> ...])
+
+
+Components and targets
+----------------------
+
+alpaqa comes with multiple optional components, some of which can be packaged
+and installed independently. The available components are:
+
++--------------+--------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------+
+|  Component   |  Description                                                                                                 |  Targets                                                                                            |
++==============+==============================================================================================================+=====================================================================================================+
+|  ``Core``    |  The main alpaqa solvers and other core functionality. If no components are specified, this is the default.  |  ``alpaqa``                                                                                         |
++--------------+--------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------+
+|  ``Dl``      |  The dynamic loading C API headers for creating problems that can be loaded by the alpaqa solvers.           |  ``dl-api``                                                                                         |
++--------------+--------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------+
+|  ``CasADi``  |  Classes for loading and building problem definitions using CasADi.                                          |  ``casadi-loader``, ``casadi-ocp-loader``                                                           |
++--------------+--------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------+
+|  ``Extra``   |  Additional solvers and problem loaders that fall outside of the core library.                               |  ``dl-loader``, ``cutest-interface``, ``ipopt-adapter``, ``lbfgsb-adapter``, ``qpalm-adapter`` ...  |
++--------------+--------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------+
+|  ``Tools``   |  Command-line tools for invoking the solvers.                                                                |  ``driver``, ``gradient-checker``                                                                   |
++--------------+--------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------+
+
+Targets are prefixed with ``alpaqa::``. For example, to link with the main alpaqa library,
+use:
+
+.. code-block:: cmake
+
+    target_link_libraries(<target> PUBLIC alpaqa::alpaqa)
+
+To check whether a certain target is available, you can use:
+
+.. code-block:: cmake
+
+    if (TARGET alpaqa::qpalm-adapter)
+        # ...
+    endif()
+
+Commands
+--------
+
+.. cmake-module::
+    ../../../../src/cmake/dl-problem.cmake
diff --git a/examples/CMake/Solver/README.md b/examples/CMake/Solver/README.md
@@ -127,26 +127,8 @@ cmake --preset conan-release # or conan-default on Windows
 cmake --build --preset conan-release -j
 ```
 
-The available components are:
-
-| Component | Description | Targets |
-|:----------|:------------|:--------|
-| `Core`    | The main alpaqa solvers and other core functionality. If no components are specified, this is the default. | `alpaqa` |
-| `Dl`      | The dynamic loading C API headers for creating problems that can be loaded by the alpaqa solvers. | `dl-api` |
-| `CasADi`  | Classes for loading and building problem definitions using CasADi. | `casadi-loader`, `casadi-ocp-loader` |
-| `Extra`   | Additional solvers and problem loaders that fall outside of the core library. | `dl-loader`, `cutest-interface`, `ipopt-adapter`, `lbfgsb-adapter`, `qpalm-adapter` ... |
-| `Tools`   | Command-line tools for invoking the solvers. | `driver`, `gradient-checker` |
-
-Some interfaces require third-party packages to be installed, and need to be
-enabled when building the Conan package (using the `-o` option).
-
-To check whether a certain target is available, you can use:
-
-```cmake
-if (TARGET alpaqa::qpalm-adapter)
-    # ...
-endif()
-```
+A complete list of the available components and targets can be found on the
+[CMake API Reference](https://kul-optec.github.io/alpaqa/1.0.0a16/Sphinx/reference/cmake-api.html) page.
 
 ### Disabling tests