Add Doxyfile, update CMake, add CI for deployment

Author: mfasi

.github/workflows/deploy_documentation.yml

@@ -0,0 +1,21 @@
+name: Documentation
+on:
+  push:
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-python@v5
+      - uses: actions/checkout@master
+
+      - name: Install and Build
+        run: |
+          sudo apt install -y doxygen graphviz python3-sphinx python3-breathe python3-sphinx-rtd-theme python3-breathe python3-exhale python3-myst-parser
+          cmake -S. -Bbuild -DBUILD_DOCS=True -DBUILD_TESTS=False -DBUILD_MEX=False
+          cmake --build build --target docs
+
+      - name: Deploy
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          branch: gh-pages
+          folder: build/docs/html

CMakeLists.txt

@@ -28,6 +28,12 @@ if (BUILD_MEX)
     add_subdirectory("mex")
 endif()
 
+# Build documentation.
+option(BUILD_DOCS "Build documentation" False)
+if (BUILD_DOCS)
+    add_subdirectory("docs")
+endif()
+
 # Build tests and check coverage, if required.
 option(CHECK_COVERAGE "Check test coverage" False)
 option(BUILD_TESTS "Run Catch2 tests" False)

docs/CMakeLists.txt

@@ -0,0 +1,23 @@
+find_package(Doxygen REQUIRED)
+
+if(DOXYGEN_FOUND)
+    configure_file(
+        "${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in"
+        "${PROJECT_BINARY_DIR}/Doxyfile"
+        COPYONLY
+    )
+
+    file(READ "${PROJECT_BINARY_DIR}/Doxyfile" DOXYFILE_CONTENT)
+    string(REPLACE "@PROJECT_NAME@" "${PROJECT_NAME}" DOXYFILE_CONTENT "${DOXYFILE_CONTENT}")
+    string(REPLACE "@PROJECT_VERSION@" "${PROJECT_VERSION}" DOXYFILE_CONTENT "${DOXYFILE_CONTENT}")
+    string(REPLACE "@PROJECT_SOURCE_DIR@" "${PROJECT_SOURCE_DIR}" DOXYFILE_CONTENT "${DOXYFILE_CONTENT}")
+    string(REPLACE "@PROJECT_BINARY_DIR@" "${PROJECT_BINARY_DIR}" DOXYFILE_CONTENT "${DOXYFILE_CONTENT}")
+    file(WRITE "${PROJECT_BINARY_DIR}/Doxyfile" "${DOXYFILE_CONTENT}")
+
+    add_custom_target(docs
+        COMMAND ${DOXYGEN_EXECUTABLE} "${CMAKE_BINARY_DIR}/Doxyfile"
+        WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/.." # Set working directory to the project root
+        COMMENT "Generating documentation with Doxygen"
+        VERBATIM
+    )
+endif()

docs/Doxyfile.in

@@ -0,0 +1,63 @@
+DOXYFILE_ENCODING             = UTF-8
+PROJECT_NAME                  = @PROJECT_NAME@
+PROJECT_NUMBER                = @PROJECT_VERSION@
+OUTPUT_DIRECTORY              = @PROJECT_BINARY_DIR@/docs/html
+CREATE_SUBDIRS                = YES
+OUTPUT_LANGUAGE               = English
+BRIEF_MEMBER_DESC             = YES
+REPEAT_BRIEF                  = YES
+MARKDOWN_SUPPORT              = YES
+TOC_INCLUDE_HEADINGS          = 3
+AUTOLINK_SUPPORT              = YES
+BUILTIN_STL_SUPPORT           = YES
+GENERATE_TREEVIEW             = YES
+ENUM_VALUES_PER_LINE          = 4
+GENERATE_HTML                 = YES
+HTML_OUTPUT                   = html
+HTML_FILE_EXTENSION           = .html
+HTML_COLORSTYLE               = LIGHT
+SEARCHENGINE                  = YES
+DISABLE_INDEX                 = NO
+TREEVIEW_WIDTH                = 300
+SEARCHDATA_FILE               = searchdata.xml
+GENERATE_BUGLIST              = YES
+GENERATE_DEPRECATEDLIST       = YES
+ENABLED_SECTIONS             += README
+INPUT                         = @PROJECT_SOURCE_DIR@/include/gemmi.hpp @PROJECT_SOURCE_DIR@/README.md
+INPUT_ENCODING                = UTF-8
+FILE_PATTERNS                 = *.h *.hpp *.c *.cpp *.md
+USE_MDFILE_AS_MAINPAGE        = @PROJECT_SOURCE_DIR@/README.md
+WARNINGS                      = YES
+WARN_IF_UNDOCUMENTED          = YES
+WARN_IF_DOC_ERROR             = YES
+WARN_NO_PARAMDOC              = YES
+WARN_NO_RETURN                = YES
+WARN_NO_EXCEPTION             = YES
+WARN_IF_INLINE_RANKS          = YES
+WARN_IF_INLINE_ORDINALS       = YES
+WARN_IF_INCOMPLETE_DOCS       = YES
+WARN_IF_MISSING_DOXYFILE      = YES
+WARN_IF_CONDITIONAL_ELSE      = YES
+WARN_IF_SYMBOL_UNDEFINED      = YES
+WARN_IF_VERSION_MISSING       = YES
+WARN_IF_USER_DEFINED_UNDEFINED= YES
+WARN_IF_UNKNOWN_COMMANDS      = YES
+WARN_NESTED_CONDITIONALS      = NO
+CHECK_INCLUDE_PATH            = YES
+SHOW_USED_FILES               = YES
+SHOW_FILES                    = YES
+SHOW_NAMESPACES               = YES
+SHOW_INCLUDE_FILES            = YES
+SHOW_GROUPED_MEMBERS          = YES
+SHOW_MODULES                  = YES
+SHOW_LICENSE                  = YES
+SORT_MEMBER_DOCS              = YES
+SORT_BRIEF_DOCS               = NO
+SORT_MEMBERS_CTORS_1ST        = NO
+SORT_GROUP_NAMES              = NO
+SORT_MODULE_NAMES             = NO
+SORT_SECTION_NAMES            = NO
+SOURCE_BROWSER                = YES
+LIST_SOURCE_CODE              = YES
+VERBATIM_HEADERS              = YES
+INLINE_INFO                   = YES