From 36cacebc27886d203fdc368c457c0fa7477c05b6 Mon Sep 17 00:00:00 2001 From: Caio Piccirillo Date: Fri, 1 May 2026 11:33:50 -0300 Subject: [PATCH] feat: Setup documentation through Doxygen --- .devcontainer/Dockerfile | 2 +- .github/workflows/docs.yml | 53 +++++++ CMakeLists.txt | 1 + CMakePresets.json | 35 +++++ Doxyfile | 300 +++++++++++++++++++++++++++++++++++++ README.md | 1 + cmake/Docs.cmake | 101 +++++++++++++ 7 files changed, 492 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/docs.yml create mode 100644 Doxyfile create mode 100644 cmake/Docs.cmake diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index 5f18392..368b313 100644 --- a/.devcontainer/Dockerfile +++ b/.devcontainer/Dockerfile @@ -13,7 +13,7 @@ RUN if [ "${REINSTALL_CMAKE_VERSION_FROM_SOURCE}" != "none" ]; then \ # [Optional] Uncomment this section to install additional packages. RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \ - && apt-get -y install --no-install-recommends lsb-release wget software-properties-common gnupg ninja-build + && apt-get -y install --no-install-recommends lsb-release wget software-properties-common gnupg ninja-build doxygen graphviz COPY ./reinstall-llvm.sh /tmp/ diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..07ede73 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,53 @@ +name: Documentation + +on: + push: + branches: [main] + + # Allow manual trigger from the Actions tab. + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: false + +jobs: + build-docs: + name: Build Documentation + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - name: Install Doxygen and Graphviz + run: | + sudo apt-get update + sudo apt-get install -y doxygen graphviz + + - name: Configure CMake + # We only need to configure so that Docs.cmake downloads the theme. + run: cmake --workflow --preset docs + + - name: Upload artifact for Pages + uses: actions/upload-pages-artifact@v3 + with: + path: build/docs/html + + deploy: + name: Deploy to GitHub Pages + needs: build-docs + runs-on: ubuntu-latest + + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/CMakeLists.txt b/CMakeLists.txt index 183c6fb..41f42da 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -9,6 +9,7 @@ list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake") include(CompileCommands) include(Coverage) +include(Docs) # Enable copying of compile_commands.json to project root copy_compile_commands() diff --git a/CMakePresets.json b/CMakePresets.json index 4e67f2a..be5176d 100644 --- a/CMakePresets.json +++ b/CMakePresets.json @@ -76,6 +76,21 @@ "STRICT_BUILD": "OFF", "ENABLE_COVERAGE": "ON" } + }, + { + "name": "config-docs", + "displayName": "Documentation", + "description": "Configure build for Doxygen documentation generation", + "binaryDir": "${sourceDir}/build/docs", + "generator": "Ninja", + "cacheVariables": { + "CMAKE_BUILD_TYPE": "Release", + "CMAKE_C_COMPILER": "/usr/bin/gcc", + "CMAKE_CXX_COMPILER": "/usr/bin/g++", + "CMAKE_EXPORT_COMPILE_COMMANDS": "ON", + "CMAKE_TOOLCHAIN_FILE": "${sourceDir}/third/vcpkg/scripts/buildsystems/vcpkg.cmake", + "STRICT_BUILD": "OFF" + } } ], "buildPresets": [ @@ -108,6 +123,13 @@ "configurePreset": "config-coverage", "displayName": "Coverage", "description": "Build with code coverage enabled" + }, + { + "name": "build-docs", + "configurePreset": "config-docs", + "displayName": "Documentation", + "description": "Build Doxygen documentation", + "targets": ["docs"] } ], "testPresets": [ @@ -214,6 +236,19 @@ "name": "test-coverage" } ] + }, + { + "name": "docs", + "steps": [ + { + "type": "configure", + "name": "config-docs" + }, + { + "type": "build", + "name": "build-docs" + } + ] } ] } diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 0000000..3a9efbf --- /dev/null +++ b/Doxyfile @@ -0,0 +1,300 @@ +# Doxyfile for cppfig — modern C++20 configuration library +# Generated for Doxygen ≥ 1.9 with doxygen-awesome-css theme. + +DOXYFILE_ENCODING = UTF-8 +PROJECT_NAME = "cppfig" +PROJECT_NUMBER = "0.1.0" +PROJECT_BRIEF = "Modern C++20 compile-time type-safe configuration library" +PROJECT_LOGO = +OUTPUT_DIRECTORY = build/docs +CREATE_SUBDIRS = NO +CREATE_SUBDIRS_LEVEL = 8 +ALLOW_UNICODE_NAMES = NO +OUTPUT_LANGUAGE = English +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ABBREVIATE_BRIEF = "The $name class" \ + "The $name widget" \ + "The $name file" \ + "is" \ + "provides" \ + "specifies" \ + "contains" \ + "represents" \ + "a" \ + "an" \ + "the" +ALWAYS_DETAILED_SEC = NO +INLINE_INHERITED_MEMB = NO +FULL_PATH_NAMES = YES +STRIP_FROM_PATH = +STRIP_FROM_INC_PATH = +SHORT_NAMES = NO +JAVADOC_AUTOBRIEF = NO +JAVADOC_BANNER = NO +QT_AUTOBRIEF = NO +MULTILINE_CPP_IS_BRIEF = NO +PYTHON_DOCSTRING = YES +INHERIT_DOCS = YES +SEPARATE_MEMBER_PAGES = NO +TAB_SIZE = 4 +ALIASES = +OPTIMIZE_OUTPUT_FOR_C = NO +OPTIMIZE_OUTPUT_JAVA = NO +OPTIMIZE_FOR_FORTRAN = NO +OPTIMIZE_OUTPUT_VHDL = NO +OPTIMIZE_OUTPUT_SLICE = NO +EXTENSION_MAPPING = +MARKDOWN_SUPPORT = YES +TOC_INCLUDE_HEADINGS = 5 +AUTOLINK_SUPPORT = YES +BUILTIN_STL_SUPPORT = YES +CPP_CLI_SUPPORT = NO +SIP_SUPPORT = NO +IDL_PROPERTY_SUPPORT = YES +DISTRIBUTE_GROUP_DOC = NO +GROUP_NESTED_COMPOUNDS = NO +SUBGROUPING = YES +INLINE_GROUPED_CLASSES = NO +INLINE_SIMPLE_STRUCTS = NO +TYPEDEF_HIDES_STRUCT = NO +LOOKUP_CACHE_SIZE = 0 +NUM_PROC_THREADS = 1 + +# Build related configuration +EXTRACT_ALL = YES +EXTRACT_PRIVATE = NO +EXTRACT_PRIV_VIRTUAL = NO +EXTRACT_PACKAGE = NO +EXTRACT_STATIC = YES +EXTRACT_LOCAL_CLASSES = YES +EXTRACT_LOCAL_METHODS = NO +EXTRACT_ANON_NSPACES = NO +RESOLVE_UNNAMED_PARAMS = YES +HIDE_UNDOC_MEMBERS = NO +HIDE_UNDOC_CLASSES = NO +HIDE_FRIEND_COMPOUNDS = NO +HIDE_IN_BODY_DOCS = NO +INTERNAL_DOCS = NO +CASE_SENSE_NAMES = YES +HIDE_SCOPE_NAMES = NO +HIDE_COMPOUND_REFERENCE= NO +SHOW_HEADERFILE = YES +SHOW_INCLUDE_FILES = YES +SHOW_GROUPED_MEMB_INC = NO +FORCE_LOCAL_INCLUDES = NO +INLINE_INFO = YES +SORT_MEMBER_DOCS = YES +SORT_BRIEF_DOCS = NO +SORT_MEMBERS_CTORS_1ST = NO +SORT_GROUP_NAMES = NO +SORT_BY_SCOPE_NAME = NO +STRICT_PROTO_MATCHING = NO +GENERATE_TODOLIST = YES +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = YES +GENERATE_DEPRECATEDLIST= YES +ENABLED_SECTIONS = +MAX_INITIALIZER_LINES = 30 +SHOW_USED_FILES = YES +SHOW_FILES = YES +SHOW_NAMESPACES = YES +FILE_VERSION_FILTER = +LAYOUT_FILE = +CITE_BIB_FILES = + +# Configuration options related to warning and progress messages +QUIET = NO +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_IF_INCOMPLETE_DOC = YES +WARN_NO_PARAMDOC = NO +WARN_IF_UNDOC_ENUM_VAL = NO +WARN_AS_ERROR = NO +WARN_FORMAT = "$file:$line: $text" +WARN_LINE_FORMAT = "at line $line of file $file" +WARN_LOGFILE = + +# Configuration options related to the input files +INPUT = README.md \ + src/ \ + docs/ +INPUT_ENCODING = UTF-8 +INPUT_FILE_ENCODING = +FILE_PATTERNS = *.c \ + *.cc \ + *.cxx \ + *.cpp \ + *.c++ \ + *.h \ + *.hh \ + *.hxx \ + *.hpp \ + *.h++ \ + *.ipp \ + *.i++ \ + *.md \ + *.dox +RECURSIVE = YES +EXCLUDE = +EXCLUDE_SYMLINKS = NO +EXCLUDE_PATTERNS = */.cache/* \ + */build/* \ + */third/* \ + */vcpkg_installed/* \ + */test/* \ + */benchmark/* \ + */examples/* +EXCLUDE_SYMBOLS = +EXAMPLE_PATH = +EXAMPLE_PATTERNS = * +EXAMPLE_RECURSIVE = NO +IMAGE_PATH = +INPUT_FILTER = +FILTER_PATTERNS = +FILTER_SOURCE_FILES = NO +FILTER_SOURCE_PATTERNS = +USE_MDFILE_AS_MAINPAGE = README.md +FORTRAN_COMMENT_AFTER = 72 + +# Configuration options related to source browsing +SOURCE_BROWSER = NO +INLINE_SOURCES = NO +STRIP_CODE_COMMENTS = YES +REFERENCED_BY_RELATION = NO +REFERENCES_RELATION = NO +REFERENCES_LINK_SOURCE = YES +SOURCE_TOOLTIPS = YES +USE_HTAGS = NO +VERBATIM_HEADERS = YES +CLANG_ASSISTED_PARSING = NO +CLANG_ADD_INC_PATHS = YES +CLANG_OPTIONS = +CLANG_DATABASE_PATH = + +# Configuration options related to the alphabetical class index +ALPHABETICAL_INDEX = YES +IGNORE_PREFIX = + +# Configuration options related to the HTML output +GENERATE_HTML = YES +HTML_OUTPUT = html +HTML_FILE_EXTENSION = .html +HTML_HEADER = +HTML_FOOTER = +HTML_STYLESHEET = +HTML_EXTRA_STYLESHEET = build/docs-theme/doxygen-awesome.css \ + build/docs-theme/doxygen-awesome-sidebar-only.css +HTML_EXTRA_FILES = build/docs-theme/doxygen-awesome-darkmode-toggle.js \ + build/docs-theme/doxygen-awesome-fragment-copy-button.js \ + build/docs-theme/doxygen-awesome-paragraph-link.js \ + build/docs-theme/doxygen-awesome-interactive-toc.js +HTML_COLORSTYLE = LIGHT +HTML_COLORSTYLE_HUE = 220 +HTML_COLORSTYLE_SAT = 100 +HTML_COLORSTYLE_GAMMA = 80 +HTML_DYNAMIC_MENUS = YES +HTML_DYNAMIC_SECTIONS = NO +HTML_INDEX_NUM_ENTRIES = 100 +GENERATE_DOCSET = NO +DOCSET_FEEDNAME = "Doxygen generated docs" +DOCSET_FEEDURL = +DOCSET_BUNDLE_ID = org.doxygen.Project +DOCSET_PUBLISHER_ID = org.doxygen.Publisher +DOCSET_PUBLISHER_NAME = Publisher +GENERATE_HTMLHELP = NO +CHM_FILE = +HHC_LOCATION = +GENERATE_CHI = NO +CHM_INDEX_ENCODING = +BINARY_TOC = NO +TOC_EXPAND = NO +GENERATE_QHP = NO +QCH_FILE = +QHP_NAMESPACE = org.doxygen.Project +QHP_VIRTUAL_FOLDER = doc +QHP_CUST_FILTER_NAME = +QHP_CUST_FILTER_ATTRS = +QHP_SECT_FILTER_ATTRS = +QHG_LOCATION = +GENERATE_ECLIPSEHELP = NO +ECLIPSE_DOC_ID = org.doxygen.Project +DISABLE_INDEX = NO +GENERATE_TREEVIEW = YES +FULL_SIDEBAR = NO +ENUM_VALUES_PER_LINE = 4 +TREEVIEW_WIDTH = 250 +EXT_LINKS_IN_WINDOW = NO +OBFUSCATE_EMAILS = YES +HTML_FORMULA_FORMAT = png +FORMULA_FONTSIZE = 10 +FORMULA_MACROFILE = +USE_MATHJAX = NO +MATHJAX_VERSION = MathJax_2 +MATHJAX_FORMAT = HTML-CSS +MATHJAX_RELPATH = +MATHJAX_EXTENSIONS = +MATHJAX_CODEFILE = +SEARCHENGINE = YES +SERVER_BASED_SEARCH = NO +EXTERNAL_SEARCH = NO +EXTERNAL_SEARCH_ID = +SEARCENGINE_URL = +SEARCHDATA_FILE = searchdata.xml +EXTERNAL_SEARCH_LINK_STYLE = +GENERATE_LATEX = NO + +# Configuration options related to the preprocessor +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = NO +EXPAND_ONLY_PREDEF = NO +SEARCH_INCLUDES = YES +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = +PREDEFINED = +EXPAND_AS_DEFINED = +SKIP_FUNCTION_MACROS = YES + +# Configuration options related to external references +TAGFILES = +GENERATE_TAGFILE = +ALLEXTERNALS = NO +EXTERNAL_GROUPS = NO +EXTERNAL_PAGES = NO + +# Configuration options related to the dot tool +CLASS_DIAGRAMS = YES +DOT_NUM_THREADS = 0 +DOT_FONTNAME = Helvetica +DOT_FONTSIZE = 10 +DOT_FONTPATH = +CLASS_GRAPH = YES +COLLABORATION_GRAPH = YES +GROUP_GRAPHS = YES +UML_LOOK = NO +UML_LIMIT_NUM_FIELDS = 10 +DOT_UML_DETAILS = NO +DOT_WRAP_THRESHOLD = 17 +TEMPLATE_RELATIONS = NO +INCLUDE_GRAPH = YES +INCLUDED_BY_GRAPH = YES +CALL_GRAPH = NO +CALLER_GRAPH = NO +GRAPHICAL_HIERARCHY = YES +DIRECTORY_GRAPH = YES +DIR_GRAPH_MAX_DEPTH = 1 +DOT_IMAGE_FORMAT = svg +INTERACTIVE_SVG = YES +DOT_PATH = +DOTFILE_DIRS = +MSCFILE_DIRS = +DIAFILE_DIRS = +PLANTUML_JAR_PATH = +PLANTUML_CFG_FILE = +PLANTUML_INCLUDE_PATH = +DOT_GRAPH_MAX_NODES = 50 +MAX_DOT_GRAPH_DEPTH = 0 +DOT_MULTI_TARGETS = NO +GENERATE_LEGEND = YES +DOT_CLEANUP = NO diff --git a/README.md b/README.md index cd19cd3..46b2a38 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ # cppfig - Modern C++20 Configuration Library [![Build Status](https://img.shields.io/badge/build-passing-brightgreen)](https://github.com/caiopiccirillo/cppfig) +[![Documentation](https://img.shields.io/badge/docs-online-blue.svg)](https://caiopiccirillo.github.io/cppfig/) [![C++ Standard](https://img.shields.io/badge/C%2B%2B-20-blue.svg)](https://en.wikipedia.org/wiki/C%2B%2B20) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) diff --git a/cmake/Docs.cmake b/cmake/Docs.cmake new file mode 100644 index 0000000..2faece6 --- /dev/null +++ b/cmake/Docs.cmake @@ -0,0 +1,101 @@ +# Docs.cmake +# CMake module for building documentation with Doxygen + doxygen-awesome-css. +# +# On first configure (or when the theme is missing), downloads the +# doxygen-awesome-css theme to CMAKE_BINARY_DIR/docs-theme/ so that +# the generated HTML uses a modern, responsive style. +# +# Usage: +# cmake -B build +# cmake --build build --target docs +# +# Public targets added: +# docs – build the Doxygen HTML documentation +# docs-serve – (optional) start a Python http.server for preview + +include(FetchContent) + +# Only enable documentation targets if Doxygen is available. +find_package(Doxygen COMPONENTS dot QUIET) + +if(NOT DOXYGEN_FOUND) + message(STATUS "Doxygen not found — documentation targets disabled") + return() +endif() + +message(STATUS "Doxygen found: ${DOXYGEN_VERSION}") + +set(_DOXYGEN_AWESOME_VERSION "2.3.4") +set(_DOXYGEN_AWESOME_DIR "${CMAKE_BINARY_DIR}/docs-theme") +set(_DOXYGEN_AWESOME_URL + "https://github.com/jothepro/doxygen-awesome-css/archive/refs/tags/v${_DOXYGEN_AWESOME_VERSION}.zip" +) + +# Download / verify the theme on first configure. +if(NOT EXISTS "${_DOXYGEN_AWESOME_DIR}/doxygen-awesome.css") + message(STATUS "Downloading doxygen-awesome-css v${_DOXYGEN_AWESOME_VERSION} ...") + + file(DOWNLOAD + ${_DOXYGEN_AWESOME_URL} + "${CMAKE_BINARY_DIR}/doxygen-awesome-css.zip" + SHOW_PROGRESS + STATUS _download_status + ) + + list(GET _download_status 0 _download_rc) + if(NOT _download_rc EQUAL 0) + list(GET _download_status 1 _download_err) + message(FATAL_ERROR "Failed to download doxygen-awesome-css: ${_download_err}") + endif() + + file(ARCHIVE_EXTRACT + INPUT "${CMAKE_BINARY_DIR}/doxygen-awesome-css.zip" + DESTINATION "${CMAKE_BINARY_DIR}/_doxygen-awesome-extract" + ) + + # The extracted folder is versioned; copy the files we need into the + # final location so the Doxyfile can reference them predictably. + file(GLOB _extracted_root + "${CMAKE_BINARY_DIR}/_doxygen-awesome-extract/doxygen-awesome-css-*" + ) + list(GET _extracted_root 0 _extracted_dir) + + file(COPY + "${_extracted_dir}/doxygen-awesome.css" + "${_extracted_dir}/doxygen-awesome-sidebar-only.css" + "${_extracted_dir}/doxygen-awesome-darkmode-toggle.js" + "${_extracted_dir}/doxygen-awesome-fragment-copy-button.js" + "${_extracted_dir}/doxygen-awesome-paragraph-link.js" + "${_extracted_dir}/doxygen-awesome-interactive-toc.js" + DESTINATION "${_DOXYGEN_AWESOME_DIR}" + ) + + # Clean up temporary artefacts. + file(REMOVE_RECURSE + "${CMAKE_BINARY_DIR}/_doxygen-awesome-extract" + "${CMAKE_BINARY_DIR}/doxygen-awesome-css.zip" + ) + + message(STATUS "doxygen-awesome-css installed in ${_DOXYGEN_AWESOME_DIR}") +else() + message(STATUS "doxygen-awesome-css already present in ${_DOXYGEN_AWESOME_DIR}") +endif() + +# Create the 'docs' target. +add_custom_target(docs + COMMAND ${DOXYGEN_EXECUTABLE} "${CMAKE_SOURCE_DIR}/Doxyfile" + WORKING_DIRECTORY ${CMAKE_SOURCE_DIR} + COMMENT "Generating Doxygen documentation" + VERBATIM +) + +# Convenience target to preview the docs locally. +find_package(Python3 COMPONENTS Interpreter QUIET) +if(Python3_FOUND) + add_custom_target(docs-serve + COMMAND ${Python3_EXECUTABLE} -m http.server 8080 + WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}/build/docs/html + COMMENT "Serving documentation at http://localhost:8080" + VERBATIM + ) +endif()