diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 0dfef9bf..2da77d58 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -14,11 +14,14 @@ jobs: - name: Checkout uses: actions/checkout@v4 - - name: Install Doxygen and Graphviz - run: sudo apt-get update && sudo apt-get install -y doxygen graphviz + - name: Install prerequisites + run: sudo apt-get update && sudo apt-get install -y cmake ninja-build doxygen graphviz - - name: Run Doxygen - run: doxygen Doxyfile + - name: Configure CMake + run: cmake -B build -G Ninja + + - name: Generate documentation + run: cmake --build build --target docs - name: Deploy to Cloudflare Pages uses: cloudflare/pages-action@v1 @@ -26,4 +29,4 @@ jobs: apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} projectName: 'internals-docs' - directory: 'docs/html' \ No newline at end of file + directory: 'build/docs/html' \ No newline at end of file diff --git a/CMakeLists.txt b/CMakeLists.txt index 9a3fda63..f58c3008 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,12 +1,60 @@ cmake_minimum_required(VERSION 3.22) project(Azin VERSION 0.0.1 LANGUAGES CXX) +if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/CMakeCache.txt" OR + EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/CMakeFiles") + message(FATAL_ERROR + "\n" + "============================================================\n" + "Azin detected a previous in-source CMake build attempt.\n" + "\n" + "Please remove the generated files from the source directory:\n" + "\n" + " rm -rf CMakeCache.txt CMakeFiles\n" + "\n" + "Then configure using:\n" + "\n" + " cmake -S . -B build\n" + " cmake --build build\n" + "\n" + "============================================================\n" + ) +endif() + +get_filename_component( + AZIN_SOURCE_DIR_REAL + "${CMAKE_CURRENT_SOURCE_DIR}" + REALPATH +) + +get_filename_component( + AZIN_BINARY_DIR_REAL + "${CMAKE_BINARY_DIR}" + REALPATH +) + +if(AZIN_SOURCE_DIR_REAL STREQUAL AZIN_BINARY_DIR_REAL) + message(FATAL_ERROR + "\n" + "============================================================\n" + "Azin does not support in-source builds.\n" + "\n" + "Remove generated files from the source directory and run:\n" + "\n" + " cmake -S . -B build\n" + " cmake --build build\n" + "\n" + "============================================================\n" + ) +endif() + list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake") include(Language) include(ProjectOptions) include(DetectCompiler) include(CompilerOptions) include(Analyzers) +include(Doxygen) include(Dependencies) diff --git a/Doxyfile b/Doxyfile.in similarity index 95% rename from Doxyfile rename to Doxyfile.in index 0d99cacd..0320b484 100644 --- a/Doxyfile +++ b/Doxyfile.in @@ -1,4 +1,4 @@ -# Doxyfile 1.17.0 +# Doxyfile 1.15.0 # This file describes the settings to be used by the documentation system # Doxygen (www.doxygen.org) for a project. @@ -42,7 +42,7 @@ DOXYFILE_ENCODING = UTF-8 # title of most generated pages and in a few other places. # The default value is: My Project. -PROJECT_NAME = "Azin" +PROJECT_NAME = "@PROJECT_NAME@" # The PROJECT_NUMBER tag can be used to enter a project or revision number. This # could be handy for archiving the generated documentation or if some version @@ -54,7 +54,7 @@ PROJECT_NUMBER = # for a project that appears at the top of each page and should give viewers a # quick idea about the purpose of the project. Keep the description short. -PROJECT_BRIEF = "The Azin programming language" +PROJECT_BRIEF = "The @PROJECT_NAME@ programming language" # With the PROJECT_LOGO tag one can specify a logo or an icon that is included # in the documentation. The maximum height of the logo should not exceed 55 @@ -74,14 +74,14 @@ PROJECT_ICON = # entered, it will be relative to the location where Doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = docs +OUTPUT_DIRECTORY = "@CMAKE_BINARY_DIR@/docs" # If the CREATE_SUBDIRS tag is set to YES then Doxygen will create up to 4096 # sub-directories (in 2 levels) under the output directory of each output format # and will distribute the generated files over these directories. Enabling this # option can be useful when feeding Doxygen a huge amount of source files, where # putting all generated files in the same directory would otherwise cause -# performance problems for the file system. Adjust CREATE_SUBDIRS_LEVEL to +# performance problems for the file system. Adapt CREATE_SUBDIRS_LEVEL to # control the number of sub-directories. # The default value is: NO. @@ -178,7 +178,7 @@ INLINE_INHERITED_MEMB = NO # shortest path that makes the file name unique will be used # The default value is: YES. -FULL_PATH_NAMES = YES +FULL_PATH_NAMES = NO # The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path. # Stripping is only done if one of the specified strings matches the left-hand @@ -190,7 +190,7 @@ FULL_PATH_NAMES = YES # will be relative from the directory where Doxygen is started. # This tag requires that the tag FULL_PATH_NAMES is set to YES. -STRIP_FROM_PATH = +STRIP_FROM_PATH = @CMAKE_SOURCE_DIR@ # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the # path mentioned in the documentation of a class, which tells the reader which @@ -290,7 +290,11 @@ TAB_SIZE = 4 # with the commands \{ and \} for these it is advised to use the version @{ and # @} or use a double escape (\\{ and \\}) -ALIASES = +ALIASES += todo="\xrefitem todo \"Todo\" \"Todo List\" " +ALIASES += invariant="\par Invariant:" +ALIASES += pre="\par Preconditions:" +ALIASES += post="\par Postconditions:" +ALIASES += complexity="\par Complexity:" # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources # only. Doxygen will then generate output that is more tailored for C. For @@ -406,8 +410,8 @@ AUTOLINK_SUPPORT = YES # This tag specifies a list of words that, when matching the start of a word in # the documentation, will suppress auto links generation, if it is enabled via -# AUTOLINK_SUPPORT. This list does not affect links explicitly created using # -# or the \link or \ref commands. +# AUTOLINK_SUPPORT. This list does not affect links explicitly created using \# +# or the \link or commands. # This tag requires that the tag AUTOLINK_SUPPORT is set to YES. AUTOLINK_IGNORE_WORDS = @@ -554,13 +558,13 @@ EXTRACT_ALL = YES # be included in the documentation. # The default value is: NO. -EXTRACT_PRIVATE = NO +EXTRACT_PRIVATE = YES # If the EXTRACT_PRIV_VIRTUAL tag is set to YES, documented private virtual # methods of a class will be included in the documentation. # The default value is: NO. -EXTRACT_PRIV_VIRTUAL = NO +EXTRACT_PRIV_VIRTUAL = YES # If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal # scope will be included in the documentation. @@ -727,7 +731,7 @@ SORT_MEMBER_DOCS = YES # this will also influence the order of the classes in the class list. # The default value is: NO. -SORT_BRIEF_DOCS = NO +SORT_BRIEF_DOCS = YES # If the SORT_MEMBERS_CTORS_1ST tag is set to YES then Doxygen will sort the # (brief and detailed) documentation of class members so that constructors and @@ -756,7 +760,7 @@ SORT_GROUP_NAMES = NO # list. # The default value is: NO. -SORT_BY_SCOPE_NAME = NO +SORT_BY_SCOPE_NAME = YES # If the STRICT_PROTO_MATCHING option is enabled and Doxygen fails to do proper # type resolution of all parameters of a function it will reject a match between @@ -793,27 +797,6 @@ GENERATE_BUGLIST = YES GENERATE_DEPRECATEDLIST= YES -# The GENERATE_REQUIREMENTS tag can be used to enable (YES) or disable (NO) the -# requirements page. When enabled, this page is automatically created when at -# least one comment block with a \requirement command appears in the input. -# The default value is: YES. - -GENERATE_REQUIREMENTS = YES - -# The REQ_TRACEABILITY_INFO tag controls if traceability information is shown on -# the requirements page (only relevant when using \requirement comment blocks). -# The setting NO will disable the traceability information altogether. The -# setting UNSATISFIED_ONLY will show a list of requirements that are missing a -# satisfies relation (through the command: \satisfies). Similarly the setting -# UNVERIFIED_ONLY will show a list of requirements that are missing a verifies -# relation (through the command: \verifies). Setting the tag to YES (the -# default) will show both lists if applicable. -# Possible values are: YES, NO, UNSATISFIED_ONLY and UNVERIFIED_ONLY. -# The default value is: YES. -# This tag requires that the tag GENERATE_REQUIREMENTS is set to YES. - -REQ_TRACEABILITY_INFO = YES - # The ENABLED_SECTIONS tag can be used to enable conditional documentation # sections, marked by \if ... \endif and \cond # ... \endcond blocks. @@ -952,7 +935,7 @@ WARN_IF_INCOMPLETE_DOC = YES # WARN_IF_INCOMPLETE_DOC # The default value is: NO. -WARN_NO_PARAMDOC = NO +WARN_NO_PARAMDOC = YES # If WARN_IF_UNDOC_ENUM_VAL option is set to YES, Doxygen will warn about # undocumented enumeration values. If set to NO, Doxygen will accept @@ -984,7 +967,7 @@ WARN_LAYOUT_FILE = YES # Possible values are: NO, YES, FAIL_ON_WARNINGS and FAIL_ON_WARNINGS_PRINT. # The default value is: NO. -WARN_AS_ERROR = NO +WARN_AS_ERROR = FAIL_ON_WARNINGS # The WARN_FORMAT tag determines the format of the warning messages that Doxygen # can produce. The string should contain the $file, $line, and $text tags, which @@ -1026,7 +1009,9 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = apps libs +INPUT = "@CMAKE_SOURCE_DIR@/apps" \ + "@CMAKE_SOURCE_DIR@/libs" \ + "@CMAKE_SOURCE_DIR@/README.md" # This tag can be used to specify the character encoding of the source files # that Doxygen parses. Internally Doxygen uses the UTF-8 encoding. Doxygen uses @@ -1075,47 +1060,13 @@ FILE_PATTERNS = *.c \ *.ccm \ *.c++ \ *.c++m \ - *.java \ - *.ii \ - *.ixx \ - *.ipp \ - *.i++ \ - *.inl \ - *.idl \ - *.ddl \ - *.odl \ *.h \ *.hh \ *.hxx \ *.hpp \ *.h++ \ - *.l \ - *.cs \ - *.d \ - *.php \ - *.php4 \ - *.php5 \ - *.phtml \ *.inc \ - *.m \ - *.markdown \ *.md \ - *.mm \ - *.dox \ - *.py \ - *.pyw \ - *.f90 \ - *.f95 \ - *.f03 \ - *.f08 \ - *.f18 \ - *.f \ - *.for \ - *.vhd \ - *.vhdl \ - *.ucf \ - *.qsf \ - *.ice # The RECURSIVE tag can be used to specify whether or not subdirectories should # be searched for input files as well. @@ -1241,7 +1192,7 @@ FILTER_SOURCE_PATTERNS = # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the Doxygen output. -USE_MDFILE_AS_MAINPAGE = +USE_MDFILE_AS_MAINPAGE = "@CMAKE_SOURCE_DIR@/README.md" # If the IMPLICIT_DIR_DOCS tag is set to YES, any README.md file found in sub- # directories of the project's root, is used as the documentation for that sub- @@ -1272,7 +1223,7 @@ FORTRAN_COMMENT_AFTER = 72 # also VERBATIM_HEADERS is set to NO. # The default value is: NO. -SOURCE_BROWSER = NO +SOURCE_BROWSER = YES # Setting the INLINE_SOURCES tag to YES will include the body of functions, # multi-line macros, enums or list initialized variables directly into the @@ -1292,13 +1243,13 @@ STRIP_CODE_COMMENTS = YES # entity all documented functions referencing it will be listed. # The default value is: NO. -REFERENCED_BY_RELATION = NO +REFERENCED_BY_RELATION = YES # If the REFERENCES_RELATION tag is set to YES then for each documented function # all documented entities called/used by that function will be listed. # The default value is: NO. -REFERENCES_RELATION = NO +REFERENCES_RELATION = YES # If the REFERENCES_LINK_SOURCE tag is set to YES and SOURCE_BROWSER tag is set # to YES then the hyperlinks from functions in REFERENCES_RELATION and @@ -1663,8 +1614,8 @@ DOCSET_PUBLISHER_NAME = Publisher # a.o. the download links, offline (the HTML help workshop was already many # years in maintenance mode). You can download the HTML help workshop from the # web archives at Installation executable (see: -# http://web.archive.org/web/20160201063255/https://download.microsoft.com/downl -# oad/0/A/9/0A939EF6-E31C-430F-A3DF-DFAE7960D564/htmlhelp.exe). +# http://web.archive.org/web/20160201063255/http://download.microsoft.com/downlo +# ad/0/A/9/0A939EF6-E31C-430F-A3DF-DFAE7960D564/htmlhelp.exe). # # The HTML Help Workshop contains a compiler that can convert all HTML output # generated by Doxygen into a single compiled HTML file (.chm). Compiled HTML @@ -1971,7 +1922,7 @@ MATHJAX_FORMAT = HTML-CSS # output directory using the MATHJAX_RELPATH option. For Mathjax version 2 the # destination directory should contain the MathJax.js script. For instance, if # the mathjax directory is located at the same level as the HTML output -# directory, then MATHJAX_RELPATH should be ../mathjax. For Mathjax versions 3 +# directory, then MATHJAX_RELPATH should be ../mathjax.s For Mathjax versions 3 # and 4 the destination directory should contain the tex-.js script # (where is either chtml or svg). The default value points to the # MathJax Content Delivery Network so you can quickly see the result without @@ -2663,7 +2614,7 @@ HIDE_UNDOC_RELATIONS = YES # https://www.graphviz.org/), a graph visualization toolkit from AT&T and Lucent # Bell Labs. The other options in this section have no effect if this option is # set to NO -# The default value is: NO. +# The default value is: YES. HAVE_DOT = YES @@ -2677,19 +2628,6 @@ HAVE_DOT = YES DOT_NUM_THREADS = 0 -# The DOT_BATCH_SIZE specifies the number of dot graphs Doxygen is allowed to -# compile in a single invocation of dot. When set to 1 Doxygen will invoke dot -# for each graph separately, which can cause significant process creation -# overhead especially on systems with many CPU cores. Together with -# DOT_NUM_THREADS this setting can be used to optimise the dot processing speed -# for a particular system. Doxygen will try to give each thread a balanced batch -# of work. If the total number of graphs to process exceeds DOT_NUM_THREADS * -# DOT_BATCH_SIZE then additional batches will be created for dot to process. -# Minimum value: 1, maximum value: 1000, default value: 50. -# This tag requires that the tag HAVE_DOT is set to YES. - -DOT_BATCH_SIZE = 50 - # DOT_COMMON_ATTR is common attributes for nodes, edges and labels of # subgraphs. When you want a differently looking font in the dot files that # Doxygen generates you can specify fontname, fontcolor and fontsize attributes. @@ -2859,7 +2797,7 @@ INCLUDED_BY_GRAPH = YES # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. -CALL_GRAPH = NO +CALL_GRAPH = YES # If the CALLER_GRAPH tag is set to YES then Doxygen will generate a caller # dependency graph for every global function or class method. @@ -2915,7 +2853,7 @@ DIR_GRAPH_MAX_DEPTH = 1 # The default value is: png. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_IMAGE_FORMAT = png +DOT_IMAGE_FORMAT = svg # If DOT_IMAGE_FORMAT is set to svg or svg:svg or svg:svg:core, then this option # can be set to YES to enable generation of interactive SVG images that allow @@ -2929,7 +2867,7 @@ DOT_IMAGE_FORMAT = png # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. -INTERACTIVE_SVG = NO +INTERACTIVE_SVG = YES # The DOT_PATH tag can be used to specify the path where the dot tool can be # found. If left blank, it is assumed the dot tool can be found in the path. @@ -2981,58 +2919,6 @@ PLANTUML_INCLUDE_PATH = PLANTUMLFILE_DIRS = -# When using Mermaid diagrams with CLI rendering, the MERMAID_PATH tag should be -# used to specify the directory where the mmdc (Mermaid CLI) executable can be -# found. If left blank, CLI-based rendering is disabled. For HTML output, -# client-side rendering via JavaScript is used by default and does not require -# mmdc. For LaTeX/PDF output, mmdc is required to pre-generate images. Doxygen -# will generate a warning when CLI rendering is needed but mmdc is not -# available. - -MERMAID_PATH = - -# When using Mermaid diagrams, the MERMAID_CONFIG_FILE tag can be used to -# specify a JSON configuration file for the Mermaid CLI tool (mmdc). This file -# can contain theme settings and other Mermaid configuration options. - -MERMAID_CONFIG_FILE = - -# The MERMAID_RENDER_MODE tag selects how Mermaid diagrams are rendered. -# Possible values are: AUTO (use client-side rendering for HTML and mmdc for -# LaTeX/PDF and other formats. If MERMAID_PATH is not set, non-HTML diagrams -# will produce a warning), CLI (use the mmdc tool to pre-generate images -# (requires Node.js and mermaid-js/mermaid-cli). Works for all output formats) -# and CLIENT_SIDE (embed mermaid.js in HTML output for client-side rendering. -# Does not require mmdc but only works for HTML output). -# The default value is: AUTO. - -MERMAID_RENDER_MODE = AUTO - -# The MERMAID_JS_URL tag specifies the URL to load mermaid.js from when using -# client-side rendering (MERMAID_RENDER_MODE is CLIENT_SIDE or AUTO). The -# default points to the latest Mermaid v11 release on the jsDelivr CDN. -# -# The default CDN URL requires internet access when viewing the generated -# documentation. For offline use, download mermaid.esm.min.mjs and set this to a -# relative path, or use MERMAID_RENDER_MODE=CLI to pre-generate images instead. -# Examples: -# - Latest v11 (default): -# 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs' -# - Pinned version: -# 'https://cdn.jsdelivr.net/npm/mermaid@11.3.0/dist/mermaid.esm.min.mjs' -# - Local copy: './mermaid.esm.min.mjs' (user must place file in HTML output -# directory) -# The default value is: -# https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs. - -MERMAID_JS_URL = https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs - -# The MERMAIDFILE_DIRS tag can be used to specify one or more directories that -# contain Mermaid files that are included in the documentation (see the -# \mermaidfile command). - -MERMAIDFILE_DIRS = - # The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of nodes # that will be shown in the graph. If the number of nodes in a graph becomes # larger than this value, Doxygen will truncate the graph, which is visualized @@ -3057,6 +2943,15 @@ DOT_GRAPH_MAX_NODES = 50 MAX_DOT_GRAPH_DEPTH = 0 +# Set the DOT_MULTI_TARGETS tag to YES to allow dot to generate multiple output +# files in one run (i.e. multiple -o and -T options on the command line). This +# makes dot run faster, but since only newer versions of dot (>1.8.10) support +# this, this feature is disabled by default. +# The default value is: NO. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_MULTI_TARGETS = NO + # If the GENERATE_LEGEND tag is set to YES Doxygen will generate a legend page # explaining the meaning of the various boxes and arrows in the dot generated # graphs. diff --git a/cmake/Doxygen.cmake b/cmake/Doxygen.cmake new file mode 100644 index 00000000..c4865883 --- /dev/null +++ b/cmake/Doxygen.cmake @@ -0,0 +1,18 @@ +find_package(Doxygen) + +if(NOT DOXYGEN_FOUND) + message(STATUS "Doxygen not found; documentation target disabled.") + return() +endif() + +configure_file( + ${PROJECT_SOURCE_DIR}/Doxyfile.in + ${PROJECT_BINARY_DIR}/Doxyfile + @ONLY +) + +add_custom_target(docs + COMMAND ${DOXYGEN_EXECUTABLE} ${PROJECT_BINARY_DIR}/Doxyfile + WORKING_DIRECTORY ${PROJECT_BINARY_DIR} + COMMENT "Generating API documentation" +) \ No newline at end of file