add sphinx/doxygen

.gitignore

 # General
 build/
 include/libcaosdbConfig.h
+.*
 
 # CMake
 CMakeLists.txt.user
@@ -139,3 +140,6 @@ flycheck_*.el
 
 ## network security
 /network-security.data
+
+# Python/Sphinx
+env/

CMakeLists.txt

@@ -8,9 +8,11 @@ project(libcaosdb
     LANGUAGES C)
 
 set(CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake" ${CMAKE_MODULE_PATH})
+set(PROJECT_INCLUDE_DIR "${PROJECT_SOURCE_DIR}/include")
 
 add_subdirectory(src)
 add_subdirectory(include)
+add_subdirectory(doc)
 
 add_library(libcaosdb STATIC ${libcaosdb_INCL} ${libcaosdb_SRC})
 add_executable(caosdbcli src/caosdbcli.c)

README.md

@@ -27,3 +27,10 @@ We use [cmocka](https://cmocka.org) for unit testing
 ## Code Formatting
 
 * `clang-format -i --verbose **/*.c **/*.h`
+
+## Documentation
+
+In the build directory, run
+
+* `cmake --build . --target doc-doxygen` (generate Doxygen)
+* `cmake --build . --target doc-sphinx` (generate Sphinx)

doc/CMakeLists.txt

+
+find_package(Doxygen)
+
+if (DOXYGEN_FOUND)
+    configure_file(Doxyfile.in Doxyfile)
+
+    # Note: do not put "ALL" - this builds docs together with application EVERY TIME!
+    add_custom_target(doc-doxygen
+        COMMAND ${DOXYGEN_EXECUTABLE} Doxyfile
+        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+        COMMENT "Generating API documentation with Doxygen"
+        VERBATIM )
+
+    find_program(SPHINX_CMD sphinx-build)
+    if (SPHINX_CMD)
+        configure_file(conf.py.in conf.py)
+
+        # create rst pages for every header file
+        list(LENGTH libcaosdb_INCL len_header_files)
+        math(EXPR len_header_files "${len_header_files} - 1")
+        foreach (i RANGE "${len_header_files}")
+            list(GET libcaosdb_INCL ${i} HEADER_FILE_NAME)
+            string(REPLACE
+                "include/"
+                ""
+                HEADER_FILE_NAME
+                ${HEADER_FILE_NAME})
+            configure_file(
+                ${CMAKE_CURRENT_SOURCE_DIR}/api/header_file.rst.in
+                ${CMAKE_CURRENT_SOURCE_DIR}/api/_${HEADER_FILE_NAME}.rst)
+        endforeach ()
+
+        add_custom_target(doc-sphinx
+            COMMAND ${SPHINX_CMD}
+                -b html
+                -n
+                -c ${CMAKE_CURRENT_BINARY_DIR}
+                ${CMAKE_CURRENT_SOURCE_DIR}
+                sphinx_out
+            DEPENDS doc-doxygen
+            WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+            COMMENT "Generating API documentation with Sphinx"
+            VERBATIM )
+    else ()
+        message("Sphinx need to be installed to generate the sphinx documentation")
+    endif ()
+
+else ()
+  message("Doxygen need to be installed to generate the doxygen documentation")
+endif (DOXYGEN_FOUND)

doc/api/.gitignore

+_*.rst

doc/api/header_file.rst.in

+.. _api_@HEADER_FILE_NAME@:
+
+@HEADER_FILE_NAME@
+===========================================
+
+.. toctree::
+    :hidden:
+
+.. doxygenfile:: @HEADER_FILE_NAME@
+   :project: libcaosdb

doc/api/index.rst

+.. _api_root:
+
+API
+===
+
+.. toctree::
+    :glob:
+
+    *

doc/conf.py.in

+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = '@CMAKE_PROJECT_NAME@'
+copyright = '2021 IndiScale GmbH'
+author = 'Timm Fitschen'
+
+rst_prolog = """
+.. |PROJECT_NAME| replace:: @CMAKE_PROJECT_NAME@
+"""
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.autosectionlabel',
+    'sphinx.ext.todo',
+    'sphinx.ext.coverage',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.ifconfig',
+    'sphinx.ext.viewcode',
+    'sphinx_sitemap',
+    'sphinx.ext.inheritance_diagram',
+    'breathe'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+# templates_path = ['@CMAKE_CURRENT_SOURCE_DIR@/_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+highlight_language = 'C'
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = ['@CMAKE_CURRENT_SOURCE_DIR@/_static']
+
+# -- Breathe configuration -------------------------------------------------
+
+breathe_projects = {
+    "@CMAKE_PROJECT_NAME@": "@CMAKE_CURRENT_BINARY_DIR@/doxygen_out/xml/"
+}
+breathe_default_project = "@CMAKE_PROJECT_NAME@"
+breathe_default_members = ('members', 'undoc-members')

doc/index.rst

+.. _welcome:
+
+Welcome to |PROJECT_NAME|'s documentation!
+==========================================
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+
+.. toctree::
+    :maxdepth: 4
+    :caption: Contents:
+
+    Welcome <self>
+    api/index

include/connection.h

+/**
+ * @file connection.h
+ * @author Timm Fitschen
+ * @date 2021-05-18
+ * @brief Configuration and setup of the connection.
+ */
+
+/**
+ * @brief Configure the connection.
+ * @param host Host name or ip address of the CaosDB server.
+ * @param port Port of the CaosDB server.
+ * @return 0 if everything is ok.
+ */
 int configure_connection(char host[], int port);

test/CMakeLists.txt

@@ -7,13 +7,13 @@ set(test_cases
 
 list(LENGTH test_cases len_test_cases)
 math(EXPR len_test_cases "${len_test_cases} - 1")
-foreach(i RANGE "${len_test_cases}")
+foreach (i RANGE "${len_test_cases}")
     list(GET test_cases ${i} test_case_name)
     add_executable(${test_case_name} ${test_case_name}.c)
     target_compile_features(${test_case_name} PRIVATE c_std_99)
     target_link_libraries(${test_case_name} PRIVATE cmocka-static libcaosdb)
     add_test(${test_case_name} ${test_case_name})
-endforeach()
+endforeach ()
 
 #add_executable(test_connection test_connection.c)
 #target_compile_features(test_connection PRIVATE c_std_99)
@@ -23,7 +23,7 @@ endforeach()
 # code coverage report
 include(CodeCoverage)
 
-if(LCOV_PATH)
+if (LCOV_PATH)
     setup_target_for_coverage_lcov(
         NAME unit_test_coverage
         EXECUTABLE ctest
@@ -31,7 +31,7 @@ if(LCOV_PATH)
         LCOV_ARGS --rc lcov_branch_coverage=1
         GENHTML_ARGS --rc lcov_branch_coverage=1
         )
-else()
+else ()
     message(WARNING "Could not generate code coverage report. Please install lcov.")
-endif()
+endif ()