From 0c3d9cb8c76dac5f9aff3a46e12e9b4c8f5c393d Mon Sep 17 00:00:00 2001 From: Peter van der Meer Date: Sun, 22 Sep 2024 21:18:44 +0200 Subject: [PATCH] feat(docs): Doxygen automatic code documentation (#10134) --- .github/path-filters.yml | 3 + .github/workflows/ci.yml | 21 +++++ .github/workflows/compute-changes.yml | 2 + .gitignore | 3 + Doxyfile | 110 ++++++++++++++++++++++++++ 5 files changed, 139 insertions(+) create mode 100644 Doxyfile diff --git a/.github/path-filters.yml b/.github/path-filters.yml index a63cc3e6eeb1..bd2a22fe545c 100644 --- a/.github/path-filters.yml +++ b/.github/path-filters.yml @@ -14,6 +14,9 @@ unit_tests: integration_tests: - 'tests/integration/config/plugins/integration-tests/**' +doxygen_config: + - 'Doxyfile' + codespell: - .codespell.exclude - .codespell.words.exclude diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5ab5193cce6f..6d77a5210f10 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -14,6 +14,7 @@ on: - '.github/workflows/**' - 'CMakeLists.txt' - 'CMakePresets.json' + - Doxyfile - keys.txt pull_request: # Run for any push to any pull request, if it modifies source code or game text. @@ -25,6 +26,7 @@ on: - '.github/workflows/**' - 'CMakeLists.txt' - 'CMakePresets.json' + - Doxyfile - keys.txt @@ -193,6 +195,25 @@ jobs: run: ctest --preset macos-ci-benchmark + build_documentation_doxygen: + name: Documentation Doxygen + needs: changed + if: ${{ needs.changed.outputs.game_code == 'true' || needs.changed.outputs.unit_tests == 'true' || needs.changed.outputs.doxygen_config == 'true' || needs.changed.outputs.ci_config == 'true'}} + runs-on: ubuntu-24.04 + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + steps: + - uses: actions/checkout@v4 + with: + show-progress: false + - name: Install development dependencies + run: | + sudo apt-get update + sudo apt-get install -y --no-install-recommends doxygen graphviz clang + - name: Run Doxygen + run: doxygen + + test-parse: needs: [changed, build_windows] name: Data Files diff --git a/.github/workflows/compute-changes.yml b/.github/workflows/compute-changes.yml index e9493370f6cb..a1ddd69dc35a 100644 --- a/.github/workflows/compute-changes.yml +++ b/.github/workflows/compute-changes.yml @@ -11,6 +11,8 @@ on: value: ${{ jobs.changed.outputs.unit_tests }} integration_tests: value: ${{ jobs.changed.outputs.integration_tests }} + doxygen_config: + value: ${{ jobs.changed.outputs.doxygen_config }} codespell: value: ${{ jobs.changed.outputs.codespell }} editorconfig_files: diff --git a/.gitignore b/.gitignore index 0ee68890c409..a60223ed6b92 100644 --- a/.gitignore +++ b/.gitignore @@ -31,6 +31,9 @@ scons-local* # Test Reports test-report.xml +# Generated documentation +docs/api/ + # User-installed plugins /plugins/ diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 000000000000..f8f541eb67de --- /dev/null +++ b/Doxyfile @@ -0,0 +1,110 @@ +# Doxyfile 1.9.4 + +# This file describes the settings to be used by the documentation system +# doxygen (www.doxygen.org) for a project. +# +# All text after a double hash (##) is considered a comment and is placed in +# front of the TAG it is preceding. +# +# All text after a single hash (#) is considered a comment and will be ignored. +# The format is: +# TAG = value [value, ...] +# For lists, items can also be appended using: +# TAG += value [value, ...] +# Values that contain spaces should be placed between quotes (\" \"). +# +# Note: +# +# Use doxygen to compare the used configuration file with the template +# configuration file: +# doxygen -x [configFile] +# Use doxygen to compare the used configuration file with the template +# configuration file without replacing the environment variables: +# doxygen -x_noenv [configFile] + +DOXYFILE_ENCODING = UTF-8 +PROJECT_NAME = "Endless Sky" +PROJECT_NUMBER = +PROJECT_BRIEF = "This is an auto generated documentation for the source code of endless-sky." +PROJECT_LOGO = icons/icon_48x48.png +OUTPUT_DIRECTORY = ./docs/api + +CREATE_SUBDIRS = YES + +INPUT = ./source +RECURSIVE = YES +EXCLUDE = +EXCLUDE_SYMLINKS = YES + +EXTRACT_ALL = YES +EXTRACT_PRIVATE = YES +EXTRACT_PRIV_VIRTUAL = YES +EXTRACT_STATIC = YES +EXTRACT_LOCAL_CLASSES = YES +EXTRACT_ANON_NSPACES = YES + +WARN_NO_PARAMDOC = YES +WARN_AS_ERROR = NO +WARN_LOGFILE = + +CLANG_ASSISTED_PARSING = YES +CLANG_ADD_INC_PATHS = YES +CLANG_OPTIONS = -std=c++20 +CLANG_DATABASE_PATH = + +GENERATE_LATEX = NO +GENERATE_HTML = YES +HTML_OUTPUT = html +HTML_FILE_EXTENSION = .html +HTML_HEADER = +HTML_FOOTER = +HTML_STYLESHEET = +HTML_EXTRA_STYLESHEET = +HTML_EXTRA_FILES = +HTML_DYNAMIC_MENUS = YES +HTML_DYNAMIC_SECTIONS = NO +HTML_INDEX_NUM_ENTRIES = 100 + +GENERATE_TREEVIEW = NO +FULL_SIDEBAR = NO +TREEVIEW_WIDTH = 250 + +HTML_FORMULA_FORMAT = svg +FORMULA_FONTSIZE = 10 +USE_MATHJAX = NO +MATHJAX_VERSION = MathJax_2 +MATHJAX_FORMAT = HTML-CSS +MATHJAX_RELPATH = +MATHJAX_EXTENSIONS = +MATHJAX_CODEFILE = + +SEARCH_INCLUDES = YES +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = +PREDEFINED = + +HAVE_DOT = YES +DOT_NUM_THREADS = 0 +DOT_FONTPATH = + +CLASS_GRAPH = YES +COLLABORATION_GRAPH = YES +GROUP_GRAPHS = YES +UML_LOOK = YES +UML_LIMIT_NUM_FIELDS = 10 +DOT_UML_DETAILS = NO +DOT_WRAP_THRESHOLD = 17 +INCLUDE_GRAPH = YES +INCLUDED_BY_GRAPH = YES +CALL_GRAPH = YES +CALLER_GRAPH = YES +GRAPHICAL_HIERARCHY = YES +DIRECTORY_GRAPH = YES +DIR_GRAPH_MAX_DEPTH = 1 + +DOT_IMAGE_FORMAT = svg +INTERACTIVE_SVG = YES +DOT_GRAPH_MAX_NODES = 50 +MAX_DOT_GRAPH_DEPTH = 0 +DOT_MULTI_TARGETS = NO +DOT_CLEANUP = YES