From 93c2e7d686ba678991185e711533ce29826b5374 Mon Sep 17 00:00:00 2001 From: George Kiagiadakis Date: Mon, 17 May 2021 15:48:38 +0300 Subject: [PATCH] meson: refactor docs + gi build system * Use custom_target() instead of configured shell scripts * Do not copy all the .rst files in the build directory * Setup dependencies between targets * Tidy up dependencies lookup * Remove unused files * Upgrade Doxyfile to the latest version and cleanup used options --- docs/{doxyfile.in => Doxyfile.in} | 563 +++++++++++------- docs/api/meson.build | 8 +- docs/conf.py.in | 32 +- ...gen-api-gtkdoc.py.in => gen-api-gtkdoc.py} | 0 docs/meson.build | 240 ++++---- docs/requirements.txt | 5 - docs/run_doxygen_sphinx.sh.in | 2 - docs/run_gen_api.sh.in | 2 - docs/toc/lua_api/meson.build | 8 +- docs/toc/meson.build | 8 +- lib/wp/meson.build | 45 +- meson.build | 4 - 12 files changed, 494 insertions(+), 423 deletions(-) rename docs/{doxyfile.in => Doxyfile.in} (85%) rename docs/{gen-api-gtkdoc.py.in => gen-api-gtkdoc.py} (100%) delete mode 100644 docs/requirements.txt delete mode 100755 docs/run_doxygen_sphinx.sh.in delete mode 100755 docs/run_gen_api.sh.in diff --git a/docs/doxyfile.in b/docs/Doxyfile.in similarity index 85% rename from docs/doxyfile.in rename to docs/Doxyfile.in index 53102b72..c18f61ce 100644 --- a/docs/doxyfile.in +++ b/docs/Doxyfile.in @@ -1,4 +1,4 @@ -# Doxyfile 1.8.13 +# Doxyfile 1.9.1 # This file describes the settings to be used by the documentation system # doxygen (www.doxygen.org) for a project. @@ -17,11 +17,11 @@ # Project related configuration options #--------------------------------------------------------------------------- -# This tag specifies the encoding used for all characters in the config file -# that follow. The default is UTF-8 which is also the encoding used for all text -# before the first occurrence of this tag. Doxygen uses libiconv (or the iconv -# built into libc) for the transcoding. See http://www.gnu.org/software/libiconv -# for the list of possible encodings. +# This tag specifies the encoding used for all characters in the configuration +# file that follow. The default is UTF-8 which is also the encoding used for all +# text before the first occurrence of this tag. Doxygen uses libiconv (or the +# iconv built into libc) for the transcoding. See +# https://www.gnu.org/software/libiconv/ for the list of possible encodings. # The default value is: UTF-8. DOXYFILE_ENCODING = UTF-8 @@ -32,7 +32,7 @@ DOXYFILE_ENCODING = UTF-8 # title of most generated pages and in a few other places. # The default value is: My Project. -PROJECT_NAME = "WirePlumber" +PROJECT_NAME = WirePlumber # 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 @@ -93,6 +93,14 @@ ALLOW_UNICODE_NAMES = NO OUTPUT_LANGUAGE = English +# The OUTPUT_TEXT_DIRECTION tag is used to specify the direction in which all +# documentation generated by doxygen is written. Doxygen will use this +# information to generate all generated output in the proper direction. +# Possible values are: None, LTR, RTL and Context. +# The default value is: None. + +OUTPUT_TEXT_DIRECTION = None + # If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member # descriptions after the members that are listed in the file and class # documentation (similar to Javadoc). Set to NO to disable this. @@ -187,7 +195,17 @@ SHORT_NAMES = NO # description.) # The default value is: NO. -JAVADOC_AUTOBRIEF = YES +JAVADOC_AUTOBRIEF = NO + +# If the JAVADOC_BANNER tag is set to YES then doxygen will interpret a line +# such as +# /*************** +# as being the beginning of a Javadoc-style comment "banner". If set to NO, the +# Javadoc-style will behave just like regular comments and it will not be +# interpreted by doxygen. +# The default value is: NO. + +JAVADOC_BANNER = NO # If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first # line (until the first dot) of a Qt-style comment as the brief description. If @@ -209,6 +227,14 @@ QT_AUTOBRIEF = NO MULTILINE_CPP_IS_BRIEF = NO +# By default Python docstrings are displayed as preformatted text and doxygen's +# special commands cannot be used. By setting PYTHON_DOCSTRING to NO the +# doxygen's special commands can be used and the contents of the docstring +# documentation blocks is shown as doxygen documentation. +# The default value is: YES. + +PYTHON_DOCSTRING = YES + # If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the # documentation from any documented member that it re-implements. # The default value is: YES. @@ -236,19 +262,17 @@ TAB_SIZE = 8 # will allow you to put the command \sideeffect (or @sideeffect) in the # documentation, which will result in a user-defined paragraph with heading # "Side Effects:". You can put \n's in the value part of an alias to insert -# newlines. +# newlines (in the resulting output). You can put ^^ in the value part of an +# alias to insert a newline as if a physical newline was in the original file. +# When you need a literal { or } or , in the value part of an alias you have to +# escape them by means of a backslash (\), this can lead to conflicts with the +# commands \{ and \} for these it is advised to use the version @{ and @} or use +# a double escape (\\{ and \\}) -ALIASES = "rst=\verbatim embed:rst:leading-asterisk" -ALIASES += "endrst=\endverbatim" - -ALIASES += "signal=\xrefitem signal \"Signal\" \"Signals\" " -ALIASES += "props=\xrefitem props \"Property\" \"Properties\" " - -# This tag can be used to specify a number of word-keyword mappings (TCL only). -# A mapping has the form "name=value". For example adding "class=itcl::class" -# will allow you to use the command class in the itcl::class meaning. - -#TCL_SUBST = +ALIASES = "rst=\verbatim embed:rst:leading-asterisk" \ + endrst=\endverbatim \ + "signal=\xrefitem signal \"Signal\" \"Signals\"" \ + "props=\xrefitem props \"Property\" \"Properties\"" # 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 @@ -278,28 +302,40 @@ OPTIMIZE_FOR_FORTRAN = NO OPTIMIZE_OUTPUT_VHDL = NO +# Set the OPTIMIZE_OUTPUT_SLICE tag to YES if your project consists of Slice +# sources only. Doxygen will then generate output that is more tailored for that +# language. For instance, namespaces will be presented as modules, types will be +# separated into more groups, etc. +# The default value is: NO. + +OPTIMIZE_OUTPUT_SLICE = NO + # Doxygen selects the parser to use depending on the extension of the files it # parses. With this tag you can assign which parser to use for a given # extension. Doxygen has a built-in mapping, but you can override or extend it # using this tag. The format is ext=language, where ext is a file extension, and -# language is one of the parsers supported by doxygen: IDL, Java, Javascript, -# C#, C, C++, D, PHP, Objective-C, Python, Fortran (fixed format Fortran: -# FortranFixed, free formatted Fortran: FortranFree, unknown formatted Fortran: -# Fortran. In the later case the parser tries to guess whether the code is fixed -# or free formatted code, this is the default for Fortran type files), VHDL. For -# instance to make doxygen treat .inc files as Fortran files (default is PHP), -# and .f files as C (default is Fortran), use: inc=Fortran f=C. +# language is one of the parsers supported by doxygen: IDL, Java, JavaScript, +# Csharp (C#), C, C++, D, PHP, md (Markdown), Objective-C, Python, Slice, VHDL, +# Fortran (fixed format Fortran: FortranFixed, free formatted Fortran: +# FortranFree, unknown formatted Fortran: Fortran. In the later case the parser +# tries to guess whether the code is fixed or free formatted code, this is the +# default for Fortran type files). For instance to make doxygen treat .inc files +# as Fortran files (default is PHP), and .f files as C (default is Fortran), +# use: inc=Fortran f=C. # # Note: For files without extension you can use no_extension as a placeholder. # # Note that for custom extensions you also need to set FILE_PATTERNS otherwise -# the files are not read by doxygen. +# the files are not read by doxygen. When specifying no_extension you should add +# * to the FILE_PATTERNS. +# +# Note see also the list of default file extension mappings. -EXTENSION_MAPPING = lua=C++ +EXTENSION_MAPPING = # If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments # according to the Markdown format, which allows for more readable -# documentation. See http://daringfireball.net/projects/markdown/ for details. +# documentation. See https://daringfireball.net/projects/markdown/ for details. # The output of markdown processing is further processed by doxygen, so you can # mix doxygen, HTML, and XML commands with Markdown formatting. Disable only in # case of backward compatibilities issues. @@ -311,10 +347,10 @@ MARKDOWN_SUPPORT = YES # to that level are automatically included in the table of contents, even if # they do not have an id attribute. # Note: This feature currently applies only to Markdown headings. -# Minimum value: 0, maximum value: 99, default value: 0. +# Minimum value: 0, maximum value: 99, default value: 5. # This tag requires that the tag MARKDOWN_SUPPORT is set to YES. -TOC_INCLUDE_HEADINGS = 0 +TOC_INCLUDE_HEADINGS = 5 # When enabled doxygen tries to link words that correspond to documented # classes, or namespaces to their corresponding documentation. Such a link can @@ -341,7 +377,7 @@ BUILTIN_STL_SUPPORT = NO CPP_CLI_SUPPORT = NO # Set the SIP_SUPPORT tag to YES if your project consists of sip (see: -# http://www.riverbankcomputing.co.uk/software/sip/intro) sources only. Doxygen +# https://www.riverbankcomputing.com/software/sip/intro) sources only. Doxygen # will parse them like normal C++ but will assume all classes use public instead # of private inheritance when no explicit protection keyword is present. # The default value is: NO. @@ -427,6 +463,19 @@ TYPEDEF_HIDES_STRUCT = NO LOOKUP_CACHE_SIZE = 0 +# The NUM_PROC_THREADS specifies the number threads doxygen is allowed to use +# during processing. When set to 0 doxygen will based this on the number of +# cores available in the system. You can set it explicitly to a value larger +# than 0 to get more control over the balance between CPU load and processing +# speed. At this moment only the input processing can be done using multiple +# threads. Since this is still an experimental feature the default is set to 1, +# which efficively disables parallel processing. Please report any issues you +# encounter. Generating dot graphs in parallel is controlled by the +# DOT_NUM_THREADS setting. +# Minimum value: 0, maximum value: 32, default value: 1. + +NUM_PROC_THREADS = 1 + #--------------------------------------------------------------------------- # Build related configuration options #--------------------------------------------------------------------------- @@ -447,6 +496,12 @@ EXTRACT_ALL = NO EXTRACT_PRIVATE = NO +# 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 + # If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal # scope will be included in the documentation. # The default value is: NO. @@ -484,6 +539,13 @@ EXTRACT_LOCAL_METHODS = NO EXTRACT_ANON_NSPACES = NO +# If this flag is set to YES, the name of an unnamed parameter in a declaration +# will be determined by the corresponding definition. By default unnamed +# parameters remain unnamed in the output. +# The default value is: YES. + +RESOLVE_UNNAMED_PARAMS = YES + # If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all # undocumented members inside documented classes or files. If set to NO these # members will be included in the various overviews, but no documentation @@ -501,8 +563,8 @@ HIDE_UNDOC_MEMBERS = YES HIDE_UNDOC_CLASSES = YES # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend -# (class|struct|union) declarations. If set to NO, these declarations will be -# included in the documentation. +# declarations. If set to NO, these declarations will be included in the +# documentation. # The default value is: NO. HIDE_FRIEND_COMPOUNDS = NO @@ -521,11 +583,18 @@ HIDE_IN_BODY_DOCS = NO INTERNAL_DOCS = NO -# If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file -# names in lower-case letters. If set to YES, upper-case letters are also -# allowed. This is useful if you have classes or files whose names only differ -# in case and if your file system supports case sensitive file names. Windows -# and Mac users are advised to set this option to NO. +# With the correct setting of option CASE_SENSE_NAMES doxygen will better be +# able to match the capabilities of the underlying filesystem. In case the +# filesystem is case sensitive (i.e. it supports files in the same directory +# whose names only differ in casing), the option must be set to YES to properly +# deal with such files in case they appear in the input. For filesystems that +# are not case sensitive the option should be be set to NO to properly deal with +# output files written for symbols that only differ in casing, such as for two +# classes, one named CLASS and the other named Class, and to also support +# references to files without having to specify the exact matching casing. On +# Windows (including Cygwin) and MacOS, users should typically set this option +# to NO, whereas on Linux or other Unix flavors it should typically be set to +# YES. # The default value is: system dependent. CASE_SENSE_NAMES = YES @@ -566,6 +635,7 @@ FORCE_LOCAL_INCLUDES = NO # If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the # documentation for inline members. # The default value is: YES. + INLINE_INFO = YES # If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the @@ -711,7 +781,7 @@ LAYOUT_FILE = # The CITE_BIB_FILES tag can be used to specify one or more bib files containing # the reference definitions. This must be a list of .bib files. The .bib # extension is automatically appended if omitted. This requires the bibtex tool -# to be installed. See also http://en.wikipedia.org/wiki/BibTeX for more info. +# to be installed. See also https://en.wikipedia.org/wiki/BibTeX for more info. # For LaTeX the style of the bibliography can be controlled using # LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the # search path. See also \cite for info how to create references. @@ -736,14 +806,14 @@ QUIET = YES # Tip: Turn warnings on while writing the documentation. # The default value is: YES. -WARNINGS = NO +WARNINGS = YES # If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate # warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag # will automatically be disabled. # The default value is: YES. -WARN_IF_UNDOCUMENTED = NO +WARN_IF_UNDOCUMENTED = YES # If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for # potential errors in the documentation, such as not documenting some parameters @@ -751,18 +821,22 @@ WARN_IF_UNDOCUMENTED = NO # markup commands wrongly. # The default value is: YES. -WARN_IF_DOC_ERROR = NO +WARN_IF_DOC_ERROR = YES # This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that # are documented, but have no documentation for their parameters or return # value. If set to NO, doxygen will only warn about wrong or incomplete -# parameter documentation, but not about the absence of documentation. +# parameter documentation, but not about the absence of documentation. If +# EXTRACT_ALL is set to YES then this flag will automatically be disabled. # The default value is: NO. WARN_NO_PARAMDOC = NO # If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when -# a warning is encountered. +# a warning is encountered. If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS +# then doxygen will continue running as if WARN_AS_ERROR tag is set to NO, but +# at the end of the doxygen process doxygen will return with a non-zero status. +# Possible values are: NO, YES and FAIL_ON_WARNINGS. # The default value is: NO. WARN_AS_ERROR = NO @@ -793,15 +867,13 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = @SRC_ROOT@/lib/wp -INPUT += @SRC_ROOT@/modules/module-lua-scripting/api.c -INPUT += @SRC_ROOT@/modules/module-lua-scripting/pod.c +INPUT = @INPUT@ # 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 # libiconv (or the iconv built into libc) for the transcoding. See the libiconv -# documentation (see: http://www.gnu.org/software/libiconv) for the list of -# possible encodings. +# documentation (see: +# https://www.gnu.org/software/libiconv/) for the list of possible encodings. # The default value is: UTF-8. INPUT_ENCODING = UTF-8 @@ -814,62 +886,23 @@ INPUT_ENCODING = UTF-8 # need to set EXTENSION_MAPPING for the extension otherwise the files are not # read by doxygen. # +# Note the list of default checked file patterns might differ from the list of +# default file extension mappings. +# # If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp, # *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, # *.hh, *.hxx, *.hpp, *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, -# *.m, *.markdown, *.md, *.mm, *.dox, *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, -# *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf and *.qsf. +# *.m, *.markdown, *.md, *.mm, *.dox (to be provided as doxygen C comment), +# *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f18, *.f, *.for, *.vhd, *.vhdl, +# *.ucf, *.qsf and *.ice. -FILE_PATTERNS = *.c \ - *.cc \ - *.cxx \ - *.cpp \ - *.c++ \ - *.java \ - *.ii \ - *.ixx \ - *.ipp \ - *.i++ \ - *.inl \ - *.idl \ - *.ddl \ - *.odl \ - *.h \ - *.hh \ - *.hxx \ - *.hpp \ - *.h++ \ - *.cs \ - *.d \ - *.php \ - *.php4 \ - *.php5 \ - *.phtml \ - *.inc \ - *.m \ - *.markdown \ - *.md \ - *.mm \ - *.dox \ - *.py \ - *.pyw \ - *.f90 \ - *.f95 \ - *.f03 \ - *.f08 \ - *.f \ - *.for \ - *.tcl \ - *.vhd \ - *.vhdl \ - *.ucf \ - *.qsf +FILE_PATTERNS = # The RECURSIVE tag can be used to specify whether or not subdirectories should # be searched for input files as well. # The default value is: NO. -RECURSIVE = YES +RECURSIVE = NO # The EXCLUDE tag can be used to specify files and/or directories that should be # excluded from the INPUT source files. This way you can easily exclude a @@ -878,7 +911,7 @@ RECURSIVE = YES # Note that relative paths are relative to the directory from which doxygen is # run. -EXCLUDE = @SRC_ROOT@/lib/wp/private +EXCLUDE = # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded @@ -894,7 +927,7 @@ EXCLUDE_SYMLINKS = NO # Note that the wildcards are matched against the file with absolute path, so to # exclude all test directories for example use the pattern */test/* -EXCLUDE_PATTERNS = debug.* +EXCLUDE_PATTERNS = # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names # (namespaces, classes, functions, etc.) that should be excluded from the @@ -905,18 +938,15 @@ EXCLUDE_PATTERNS = debug.* # Note that the wildcards are matched against the file with absolute path, so to # exclude all test directories use the pattern */test/* -EXCLUDE_SYMBOLS = G_DEFINE_TYPE_WITH_CODE -EXCLUDE_SYMBOLS += G_DEFINE_QUARK -EXCLUDE_SYMBOLS += G_DEFINE_TYPE_WITH_PRIVATE -EXCLUDE_SYMBOLS += G_DEFINE_ABSTRACT_TYPE -EXCLUDE_SYMBOLS += G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE -EXCLUDE_SYMBOLS += G_DECLARE_DERIVABLE_TYPE -EXCLUDE_SYMBOLS += G_DECLARE_FINAL_TYPE -EXCLUDE_SYMBOLS += G_DECLARE_INTERFACE - -EXCLUDE_SYMBOLS += G_LOG_* - -# Exclude the below functions that are defined in multiple C files so as to avoid errors from Sphinx/Exhale while documenting. +EXCLUDE_SYMBOLS = G_DEFINE_TYPE_WITH_CODE \ + G_DEFINE_QUARK \ + G_DEFINE_TYPE_WITH_PRIVATE \ + G_DEFINE_ABSTRACT_TYPE \ + G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE \ + G_DECLARE_DERIVABLE_TYPE \ + G_DECLARE_FINAL_TYPE \ + G_DECLARE_INTERFACE \ + G_LOG_* # The EXAMPLE_PATH tag can be used to specify one or more files or directories # that contain example code fragments that are included (see the \include @@ -963,7 +993,7 @@ IMAGE_PATH = # need to set EXTENSION_MAPPING for the extension otherwise the files are not # properly processed by doxygen. -INPUT_FILTER = +INPUT_FILTER = # The FILTER_PATTERNS tag can be used to specify filters on a per file pattern # basis. Doxygen will compare the file name with each pattern and apply the @@ -976,9 +1006,6 @@ INPUT_FILTER = # need to set EXTENSION_MAPPING for the extension otherwise the files are not # properly processed by doxygen. -# Comment out the function declarations in the header files so as to avoid errors -# from Sphinx/Exhale while documenting as it sees functions mentioned in both header -# and source files FILTER_PATTERNS = # If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using @@ -1030,7 +1057,7 @@ INLINE_SOURCES = NO STRIP_CODE_COMMENTS = YES # If the REFERENCED_BY_RELATION tag is set to YES then for each documented -# function all documented functions referencing it will be listed. +# entity all documented functions referencing it will be listed. # The default value is: NO. REFERENCED_BY_RELATION = NO @@ -1062,12 +1089,12 @@ SOURCE_TOOLTIPS = YES # If the USE_HTAGS tag is set to YES then the references to source code will # point to the HTML generated by the htags(1) tool instead of doxygen built-in # source browser. The htags tool is part of GNU's global source tagging system -# (see http://www.gnu.org/software/global/global.html). You will need version +# (see https://www.gnu.org/software/global/global.html). You will need version # 4.8.6 or higher. # # To use it do the following: # - Install the latest version of global -# - Enable SOURCE_BROWSER and USE_HTAGS in the config file +# - Enable SOURCE_BROWSER and USE_HTAGS in the configuration file # - Make sure the INPUT points to the root of the source tree # - Run doxygen as normal # @@ -1089,6 +1116,44 @@ USE_HTAGS = NO VERBATIM_HEADERS = YES +# If the CLANG_ASSISTED_PARSING tag is set to YES then doxygen will use the +# clang parser (see: +# http://clang.llvm.org/) for more accurate parsing at the cost of reduced +# performance. This can be particularly helpful with template rich C++ code for +# which doxygen's built-in parser lacks the necessary type information. +# Note: The availability of this option depends on whether or not doxygen was +# generated with the -Duse_libclang=ON option for CMake. +# The default value is: NO. + +CLANG_ASSISTED_PARSING = NO + +# If clang assisted parsing is enabled and the CLANG_ADD_INC_PATHS tag is set to +# YES then doxygen will add the directory of each input to the include path. +# The default value is: YES. + +CLANG_ADD_INC_PATHS = YES + +# If clang assisted parsing is enabled you can provide the compiler with command +# line options that you would normally use when invoking the compiler. Note that +# the include paths will already be set by doxygen for the files and directories +# specified with INPUT and INCLUDE_PATH. +# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES. + +CLANG_OPTIONS = + +# If clang assisted parsing is enabled you can provide the clang parser with the +# path to the directory containing a file called compile_commands.json. This +# file is the compilation database (see: +# http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html) containing the +# options used when the source files were built. This is equivalent to +# specifying the -p option to a clang tool, such as clang-check. These options +# will then be passed to the parser. Any options specified with CLANG_OPTIONS +# will be added as well. +# Note: The availability of this option depends on whether or not doxygen was +# generated with the -Duse_libclang=ON option for CMake. + +CLANG_DATABASE_PATH = + #--------------------------------------------------------------------------- # Configuration options related to the alphabetical class index #--------------------------------------------------------------------------- @@ -1100,13 +1165,6 @@ VERBATIM_HEADERS = YES ALPHABETICAL_INDEX = YES -# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in -# which the alphabetical index list will be split. -# Minimum value: 1, maximum value: 20, default value: 5. -# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. - -COLS_IN_ALPHA_INDEX = 5 - # In case all classes in a project start with a common prefix, all classes will # be put under the same header in the alphabetical index. The IGNORE_PREFIX tag # can be used to specify a prefix (or a list of prefixes) that should be ignored @@ -1207,7 +1265,7 @@ HTML_EXTRA_FILES = # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen # will adjust the colors in the style sheet and background images according to # this color. Hue is specified as an angle on a colorwheel, see -# http://en.wikipedia.org/wiki/Hue for more information. For instance the value +# https://en.wikipedia.org/wiki/Hue for more information. For instance the value # 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300 # purple, and 360 is red again. # Minimum value: 0, maximum value: 359, default value: 220. @@ -1243,6 +1301,17 @@ HTML_COLORSTYLE_GAMMA = 80 HTML_TIMESTAMP = NO +# If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML +# documentation will contain a main index with vertical navigation menus that +# are dynamically created via JavaScript. If disabled, the navigation index will +# consists of multiple levels of tabs that are statically embedded in every HTML +# page. Disable this option to support browsers that do not have JavaScript, +# like the Qt help browser. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_DYNAMIC_MENUS = YES + # If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML # documentation will contain sections that can be hidden and shown after the # page has loaded. @@ -1266,13 +1335,14 @@ HTML_INDEX_NUM_ENTRIES = 100 # If the GENERATE_DOCSET tag is set to YES, additional index files will be # generated that can be used as input for Apple's Xcode 3 integrated development -# environment (see: http://developer.apple.com/tools/xcode/), introduced with -# OSX 10.5 (Leopard). To create a documentation set, doxygen will generate a -# Makefile in the HTML output directory. Running make will produce the docset in -# that directory and running make install will install the docset in +# environment (see: +# https://developer.apple.com/xcode/), introduced with OSX 10.5 (Leopard). To +# create a documentation set, doxygen will generate a Makefile in the HTML +# output directory. Running make will produce the docset in that directory and +# running make install will install the docset in # ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find it at -# startup. See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html -# for more information. +# startup. See https://developer.apple.com/library/archive/featuredarticles/Doxy +# genXcode/_index.html for more information. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. @@ -1311,8 +1381,8 @@ DOCSET_PUBLISHER_NAME = Publisher # If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three # additional HTML index files: index.hhp, index.hhc, and index.hhk. The # index.hhp is a project file that can be read by Microsoft's HTML Help Workshop -# (see: http://www.microsoft.com/en-us/download/details.aspx?id=21138) on -# Windows. +# (see: +# https://www.microsoft.com/en-us/download/details.aspx?id=21138) on Windows. # # 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 @@ -1342,7 +1412,7 @@ CHM_FILE = HHC_LOCATION = # The GENERATE_CHI flag controls if a separate .chi index file is generated -# (YES) or that it should be included in the master .chm file (NO). +# (YES) or that it should be included in the main .chm file (NO). # The default value is: NO. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. @@ -1387,7 +1457,8 @@ QCH_FILE = # The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help # Project output. For more information please see Qt Help Project / Namespace -# (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#namespace). +# (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#namespace). # The default value is: org.doxygen.Project. # This tag requires that the tag GENERATE_QHP is set to YES. @@ -1395,8 +1466,8 @@ QHP_NAMESPACE = org.doxygen.Project # The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt # Help Project output. For more information please see Qt Help Project / Virtual -# Folders (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#virtual- -# folders). +# Folders (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#virtual-folders). # The default value is: doc. # This tag requires that the tag GENERATE_QHP is set to YES. @@ -1404,30 +1475,30 @@ QHP_VIRTUAL_FOLDER = doc # If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom # filter to add. For more information please see Qt Help Project / Custom -# Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom- -# filters). +# Filters (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom-filters). # This tag requires that the tag GENERATE_QHP is set to YES. QHP_CUST_FILTER_NAME = # The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the # custom filter to add. For more information please see Qt Help Project / Custom -# Filters (see: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom- -# filters). +# Filters (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom-filters). # This tag requires that the tag GENERATE_QHP is set to YES. QHP_CUST_FILTER_ATTRS = # The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this # project's filter section matches. Qt Help Project / Filter Attributes (see: -# http://qt-project.org/doc/qt-4.8/qthelpproject.html#filter-attributes). +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#filter-attributes). # This tag requires that the tag GENERATE_QHP is set to YES. QHP_SECT_FILTER_ATTRS = -# The QHG_LOCATION tag can be used to specify the location of Qt's -# qhelpgenerator. If non-empty doxygen will try to run qhelpgenerator on the -# generated .qhp file. +# The QHG_LOCATION tag can be used to specify the location (absolute path +# including file name) of Qt's qhelpgenerator. If non-empty doxygen will try to +# run qhelpgenerator on the generated .qhp file. # This tag requires that the tag GENERATE_QHP is set to YES. QHG_LOCATION = @@ -1504,6 +1575,17 @@ TREEVIEW_WIDTH = 250 EXT_LINKS_IN_WINDOW = NO +# If the HTML_FORMULA_FORMAT option is set to svg, doxygen will use the pdf2svg +# tool (see https://github.com/dawbarton/pdf2svg) or inkscape (see +# https://inkscape.org) to generate formulas as SVG images instead of PNGs for +# the HTML output. These images will generally look nicer at scaled resolutions. +# Possible values are: png (the default) and svg (looks nicer but requires the +# pdf2svg or inkscape tool). +# The default value is: png. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_FORMULA_FORMAT = png + # Use this tag to change the font size of LaTeX formulas included as images in # the HTML documentation. When you change the font size after a successful # doxygen run you need to manually remove any form_*.png images from the HTML @@ -1513,7 +1595,7 @@ EXT_LINKS_IN_WINDOW = NO FORMULA_FONTSIZE = 10 -# Use the FORMULA_TRANPARENT tag to determine whether or not the images +# Use the FORMULA_TRANSPARENT tag to determine whether or not the images # generated for formulas are transparent PNGs. Transparent PNGs are not # supported properly for IE 6.0, but are supported on all modern browsers. # @@ -1524,8 +1606,14 @@ FORMULA_FONTSIZE = 10 FORMULA_TRANSPARENT = YES +# The FORMULA_MACROFILE can contain LaTeX \newcommand and \renewcommand commands +# to create new LaTeX commands to be used in formulas as building blocks. See +# the section "Including formulas" for details. + +FORMULA_MACROFILE = + # Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see -# http://www.mathjax.org) which uses client side Javascript for the rendering +# https://www.mathjax.org) which uses client side JavaScript for the rendering # instead of using pre-rendered bitmaps. Use this if you do not have LaTeX # installed or if you want to formulas look prettier in the HTML output. When # enabled you may also need to install MathJax separately and configure the path @@ -1537,7 +1625,7 @@ USE_MATHJAX = NO # When MathJax is enabled you can set the default output format to be used for # the MathJax output. See the MathJax site (see: -# http://docs.mathjax.org/en/latest/output.html) for more details. +# http://docs.mathjax.org/en/v2.7-latest/output.html) for more details. # Possible values are: HTML-CSS (which is slower, but has the best # compatibility), NativeMML (i.e. MathML) and SVG. # The default value is: HTML-CSS. @@ -1552,11 +1640,11 @@ MATHJAX_FORMAT = HTML-CSS # MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax # Content Delivery Network so you can quickly see the result without installing # MathJax. However, it is strongly recommended to install a local copy of -# MathJax from http://www.mathjax.org before deployment. -# The default value is: http://cdn.mathjax.org/mathjax/latest. +# MathJax from https://www.mathjax.org before deployment. +# The default value is: https://cdn.jsdelivr.net/npm/mathjax@2. # This tag requires that the tag USE_MATHJAX is set to YES. -MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest +MATHJAX_RELPATH = # The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax # extension names that should be enabled during MathJax rendering. For example @@ -1567,7 +1655,8 @@ MATHJAX_EXTENSIONS = # The MATHJAX_CODEFILE tag can be used to specify a file with javascript pieces # of code that will be used on startup of the MathJax code. See the MathJax site -# (see: http://docs.mathjax.org/en/latest/output.html) for more details. For an +# (see: +# http://docs.mathjax.org/en/v2.7-latest/output.html) for more details. For an # example see the documentation. # This tag requires that the tag USE_MATHJAX is set to YES. @@ -1595,7 +1684,7 @@ MATHJAX_CODEFILE = SEARCHENGINE = YES # When the SERVER_BASED_SEARCH tag is enabled the search engine will be -# implemented using a web server instead of a web client using Javascript. There +# implemented using a web server instead of a web client using JavaScript. There # are two flavors of web server based searching depending on the EXTERNAL_SEARCH # setting. When disabled, doxygen will generate a PHP script for searching and # an index file used by the script. When EXTERNAL_SEARCH is enabled the indexing @@ -1614,7 +1703,8 @@ SERVER_BASED_SEARCH = NO # # Doxygen ships with an example indexer (doxyindexer) and search engine # (doxysearch.cgi) which are based on the open source search engine library -# Xapian (see: http://xapian.org/). +# Xapian (see: +# https://xapian.org/). # # See the section "External Indexing and Searching" for details. # The default value is: NO. @@ -1627,8 +1717,9 @@ EXTERNAL_SEARCH = NO # # Doxygen ships with an example indexer (doxyindexer) and search engine # (doxysearch.cgi) which are based on the open source search engine library -# Xapian (see: http://xapian.org/). See the section "External Indexing and -# Searching" for details. +# Xapian (see: +# https://xapian.org/). See the section "External Indexing and Searching" for +# details. # This tag requires that the tag SEARCHENGINE is set to YES. SEARCHENGINE_URL = @@ -1679,21 +1770,35 @@ LATEX_OUTPUT = latex # The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be # invoked. # -# Note that when enabling USE_PDFLATEX this option is only used for generating -# bitmaps for formulas in the HTML output, but not in the Makefile that is -# written to the output directory. -# The default file is: latex. +# Note that when not enabling USE_PDFLATEX the default is latex when enabling +# USE_PDFLATEX the default is pdflatex and when in the later case latex is +# chosen this is overwritten by pdflatex. For specific output languages the +# default can have been set differently, this depends on the implementation of +# the output language. # This tag requires that the tag GENERATE_LATEX is set to YES. -LATEX_CMD_NAME = latex +LATEX_CMD_NAME = # The MAKEINDEX_CMD_NAME tag can be used to specify the command name to generate # index for LaTeX. +# Note: This tag is used in the Makefile / make.bat. +# See also: LATEX_MAKEINDEX_CMD for the part in the generated output file +# (.tex). # The default file is: makeindex. # This tag requires that the tag GENERATE_LATEX is set to YES. MAKEINDEX_CMD_NAME = makeindex +# The LATEX_MAKEINDEX_CMD tag can be used to specify the command name to +# generate index for LaTeX. In case there is no backslash (\) as first character +# it will be automatically added in the LaTeX code. +# Note: This tag is used in the generated output file (.tex). +# See also: MAKEINDEX_CMD_NAME for the part in the Makefile / make.bat. +# The default value is: makeindex. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_MAKEINDEX_CMD = makeindex + # If the COMPACT_LATEX tag is set to YES, doxygen generates more compact LaTeX # documents. This may be useful for small projects and may help to save some # trees in general. @@ -1778,9 +1883,11 @@ LATEX_EXTRA_FILES = PDF_HYPERLINKS = YES -# If the USE_PDFLATEX tag is set to YES, doxygen will use pdflatex to generate -# the PDF file directly from the LaTeX files. Set this option to YES, to get a -# higher quality PDF documentation. +# If the USE_PDFLATEX tag is set to YES, doxygen will use the engine as +# specified with LATEX_CMD_NAME to generate the PDF file directly from the LaTeX +# files. Set this option to YES, to get a higher quality PDF documentation. +# +# See also section LATEX_CMD_NAME for selecting the engine. # The default value is: YES. # This tag requires that the tag GENERATE_LATEX is set to YES. @@ -1814,7 +1921,7 @@ LATEX_SOURCE_CODE = NO # The LATEX_BIB_STYLE tag can be used to specify the style to use for the # bibliography, e.g. plainnat, or ieeetr. See -# http://en.wikipedia.org/wiki/BibTeX and \cite for more info. +# https://en.wikipedia.org/wiki/BibTeX and \cite for more info. # The default value is: plain. # This tag requires that the tag GENERATE_LATEX is set to YES. @@ -1828,6 +1935,14 @@ LATEX_BIB_STYLE = plain LATEX_TIMESTAMP = NO +# The LATEX_EMOJI_DIRECTORY tag is used to specify the (relative or absolute) +# path from which the emoji images will be read. If a relative path is entered, +# it will be relative to the LATEX_OUTPUT directory. If left blank the +# LATEX_OUTPUT directory will be used. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_EMOJI_DIRECTORY = + #--------------------------------------------------------------------------- # Configuration options related to the RTF output #--------------------------------------------------------------------------- @@ -1867,9 +1982,9 @@ COMPACT_RTF = NO RTF_HYPERLINKS = NO -# Load stylesheet definitions from file. Syntax is similar to doxygen's config -# file, i.e. a series of assignments. You only have to provide replacements, -# missing definitions are set to their default value. +# Load stylesheet definitions from file. Syntax is similar to doxygen's +# configuration file, i.e. a series of assignments. You only have to provide +# replacements, missing definitions are set to their default value. # # See also section "Doxygen usage" for information on how to generate the # default style sheet that doxygen normally uses. @@ -1878,8 +1993,8 @@ RTF_HYPERLINKS = NO RTF_STYLESHEET_FILE = # Set optional variables used in the generation of an RTF document. Syntax is -# similar to doxygen's config file. A template extensions file can be generated -# using doxygen -e rtf extensionFile. +# similar to doxygen's configuration file. A template extensions file can be +# generated using doxygen -e rtf extensionFile. # This tag requires that the tag GENERATE_RTF is set to YES. RTF_EXTENSIONS_FILE = @@ -1965,7 +2080,12 @@ XML_OUTPUT = xml XML_PROGRAMLISTING = NO -#XML_NS_MEMB_FILE_SCOPE = YES +# If the XML_NS_MEMB_FILE_SCOPE tag is set to YES, doxygen will include +# namespace members in file scope as well, matching the HTML output. +# The default value is: NO. +# This tag requires that the tag GENERATE_XML is set to YES. + +XML_NS_MEMB_FILE_SCOPE = NO #--------------------------------------------------------------------------- # Configuration options related to the DOCBOOK output @@ -1999,9 +2119,9 @@ DOCBOOK_PROGRAMLISTING = NO #--------------------------------------------------------------------------- # If the GENERATE_AUTOGEN_DEF tag is set to YES, doxygen will generate an -# AutoGen Definitions (see http://autogen.sf.net) file that captures the -# structure of the code including all documentation. Note that this feature is -# still experimental and incomplete at the moment. +# AutoGen Definitions (see http://autogen.sourceforge.net/) file that captures +# the structure of the code including all documentation. Note that this feature +# is still experimental and incomplete at the moment. # The default value is: NO. GENERATE_AUTOGEN_DEF = NO @@ -2083,7 +2203,7 @@ SEARCH_INCLUDES = YES # preprocessor. # This tag requires that the tag SEARCH_INCLUDES is set to YES. -INCLUDE_PATH = +INCLUDE_PATH = # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard # patterns (like *.h and *.hpp) to filter out the header-files in the @@ -2101,16 +2221,16 @@ INCLUDE_FILE_PATTERNS = # recursively expanded use the := operator instead of the = operator. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -PREDEFINED = DOXYGEN_DOCUMENTATION_BUILD -PREDEFINED += DOXYGEN_SHOULD_SKIP_THIS -PREDEFINED += G_BEGIN_DECLS= -PREDEFINED += G_END_DECLS= -PREDEFINED += WP_API= -PREDEFINED += WP_PRIVATE_API= -PREDEFINED += WP_PLUGIN_EXPORT= -PREDEFINED += G_GNUC_CONST= -PREDEFINED += G_GNUC_PRINTF(...)= -PREDEFINED += GQuark= +PREDEFINED = DOXYGEN_DOCUMENTATION_BUILD \ + DOXYGEN_SHOULD_SKIP_THIS \ + G_BEGIN_DECLS= \ + G_END_DECLS= \ + WP_API= \ + WP_PRIVATE_API= \ + WP_PLUGIN_EXPORT= \ + G_GNUC_CONST= \ + G_GNUC_PRINTF(...)= \ + GQuark= # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this # tag can be used to specify a list of macro names that should be expanded. The @@ -2119,15 +2239,15 @@ PREDEFINED += GQuark= # definition found in the source code. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -EXPAND_AS_DEFINED = WP_PRIVATE_API -EXPAND_AS_DEFINED += WP_API -EXPAND_AS_DEFINED += WP_PLUGIN_EXPORT -EXPAND_AS_DEFINED += G_BEGIN_DECLS -EXPAND_AS_DEFINED += G_END_DECLS -EXPAND_AS_DEFINED += G_IMPLEMENT_INTERFACE -EXPAND_AS_DEFINED += G_GNUC_CONST -EXPAND_AS_DEFINED += G_GNUC_PRINTF -EXPAND_AS_DEFINED += GQuark +EXPAND_AS_DEFINED = WP_PRIVATE_API \ + WP_API \ + WP_PLUGIN_EXPORT \ + G_BEGIN_DECLS \ + G_END_DECLS \ + G_IMPLEMENT_INTERFACE \ + G_GNUC_CONST \ + G_GNUC_PRINTF \ + GQuark # If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will # remove all references to function-like macros that are alone on a line, have @@ -2185,12 +2305,6 @@ EXTERNAL_GROUPS = YES EXTERNAL_PAGES = YES -# The PERL_PATH should be the absolute path and name of the perl script -# interpreter (i.e. the result of 'which perl'). -# The default file (with absolute path) is: /usr/bin/perl. - -#PERL_PATH = /usr/bin/perl - #--------------------------------------------------------------------------- # Configuration options related to the dot tool #--------------------------------------------------------------------------- @@ -2202,16 +2316,7 @@ EXTERNAL_PAGES = YES # powerful graphs. # The default value is: YES. -CLASS_DIAGRAMS = YES - -# You can define message sequence charts within doxygen comments using the \msc -# command. Doxygen will then run the mscgen tool (see: -# http://www.mcternan.me.uk/mscgen/)) to produce the chart and insert it in the -# documentation. The MSCGEN_PATH tag allows you to specify the directory where -# the mscgen tool resides. If left empty the tool is assumed to be found in the -# default search path. - -#MSCGEN_PATH = +CLASS_DIAGRAMS = NO # You can include diagrams made with dia in doxygen documentation. Doxygen will # then run dia to produce the diagram and insert it in the documentation. The @@ -2233,7 +2338,7 @@ HIDE_UNDOC_RELATIONS = YES # set to NO # The default value is: YES. -HAVE_DOT = NO +HAVE_DOT = YES # The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed # to run in parallel. When set to 0 doxygen will base this on the number of @@ -2310,10 +2415,32 @@ UML_LOOK = NO # but if the number exceeds 15, the total amount of fields shown is limited to # 10. # Minimum value: 0, maximum value: 100, default value: 10. -# This tag requires that the tag HAVE_DOT is set to YES. +# This tag requires that the tag UML_LOOK is set to YES. UML_LIMIT_NUM_FIELDS = 10 +# If the DOT_UML_DETAILS tag is set to NO, doxygen will show attributes and +# methods without types and arguments in the UML graphs. If the DOT_UML_DETAILS +# tag is set to YES, doxygen will add type and arguments for attributes and +# methods in the UML graphs. If the DOT_UML_DETAILS tag is set to NONE, doxygen +# will not generate fields with class member information in the UML graphs. The +# class diagrams will look similar to the default class diagrams but using UML +# notation for the relationships. +# Possible values are: NO, YES and NONE. +# The default value is: NO. +# This tag requires that the tag UML_LOOK is set to YES. + +DOT_UML_DETAILS = NO + +# The DOT_WRAP_THRESHOLD tag can be used to set the maximum number of characters +# to display on a single line. If the actual line length exceeds this threshold +# significantly it will wrapped across multiple lines. Some heuristics are apply +# to avoid ugly line breaks. +# Minimum value: 0, maximum value: 1000, default value: 17. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_WRAP_THRESHOLD = 17 + # If the TEMPLATE_RELATIONS tag is set to YES then the inheritance and # collaboration graphs will show the relations between templates and their # instances. @@ -2486,7 +2613,7 @@ MAX_DOT_GRAPH_DEPTH = 0 # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_TRANSPARENT = YES +DOT_TRANSPARENT = NO # 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 @@ -2505,9 +2632,11 @@ DOT_MULTI_TARGETS = NO GENERATE_LEGEND = YES -# If the DOT_CLEANUP tag is set to YES, doxygen will remove the intermediate dot +# If the DOT_CLEANUP tag is set to YES, doxygen will remove the intermediate # files that are used to generate the various graphs. +# +# Note: This setting is not only used for dot files but also for msc and +# plantuml temporary files. # The default value is: YES. -# This tag requires that the tag HAVE_DOT is set to YES. DOT_CLEANUP = YES diff --git a/docs/api/meson.build b/docs/api/meson.build index c67ffcb9..fc9b4d87 100644 --- a/docs/api/meson.build +++ b/docs/api/meson.build @@ -1,5 +1,5 @@ # you need to add here any files you add to the api directory as well -files = [ +sphinx_files += files( 'library_root.rst', 'client_api.rst', 'components_api.rst', @@ -27,8 +27,4 @@ files = [ 'spa_type_api.rst', 'spa_pod_api.rst', 'wp_api.rst' -] - -foreach file : files - configure_file(input: file, output: file, copy: true) -endforeach +) diff --git a/docs/conf.py.in b/docs/conf.py.in index f29c1083..8cd79003 100644 --- a/docs/conf.py.in +++ b/docs/conf.py.in @@ -10,19 +10,19 @@ # 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('.')) +#import os +#import sys +#sys.path.insert(0, os.path.abspath('.')) # -- Project information ----------------------------------------------------- project = 'WirePlumber' -copyright = '2020, Collabora' +copyright = '2021, Collabora' author = 'Collabora' # The full version, including alpha/beta/rc tags -release = '2020' +release = '@VERSION@' # -- General configuration --------------------------------------------------- @@ -32,9 +32,13 @@ release = '2020' # ones. extensions = [ 'breathe', + 'sphinx_rtd_theme', ] -breathe_projects = { "WirePlumber": "@BUILD_ROOT@/xml", "WirePlumber_Lua" : "@BUILD_ROOT@/xml", } +breathe_projects = { + "WirePlumber": "@OUTDIR@/wp/xml", + "WirePlumber_Lua" : "@OUTDIR@/lua/xml", +} breathe_default_members = ('members', 'undoc-members') breathe_default_project = "WirePlumber" @@ -51,28 +55,22 @@ breathe_domain_by_extension = { # See, https://breathe.readthedocs.io/en/latest/directives.html#config-values for more information # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +#templates_path = ['_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'] +exclude_patterns = ['meson.build'] # -- Options for HTML output ------------------------------------------------- -# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org -on_rtd = os.environ.get('READTHEDOCS', None) == 'True' - -if not on_rtd: # only import and set the theme if we're building docs locally - import sphinx_rtd_theme - html_theme = 'sphinx_rtd_theme' - html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] +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 = ['_static'] +#html_static_path = ['_static'] # Tell sphinx what the primary language being documented is. -primary_domain = 'cpp' +primary_domain = 'c' diff --git a/docs/gen-api-gtkdoc.py.in b/docs/gen-api-gtkdoc.py similarity index 100% rename from docs/gen-api-gtkdoc.py.in rename to docs/gen-api-gtkdoc.py diff --git a/docs/meson.build b/docs/meson.build index 472dd91b..c9831d7e 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -1,130 +1,134 @@ -sphinx_p = find_program('sphinx-build', required: get_option('doc')) -if not sphinx_p.found() - message('Sphinx not found, not building the documentation') - subdir_done() -endif - -if not doxygen_p.found() - message('Doxygen not found, not building the documentation') - subdir_done() -endif - -breathe_p = find_program('breathe-apidoc', required: get_option('doc')) -if not breathe_p.found() - message('Breathe not found, not building the documentation') - subdir_done() -endif - +# Find dependencies pymod = import('python') -lxml_p = pymod.find_installation( - modules: [ - 'lxml', - ], + +python_doc = pymod.find_installation( + 'python3', + modules: ['sphinx', 'sphinx_rtd_theme', 'breathe'], required: get_option('doc') ) -if not lxml_p.found() - message('lxml not found, not building gtk documentation from Doxygen') - subdir_done() + +python_gir = pymod.find_installation( + 'python3', + modules: ['lxml'], + required: get_option('introspection') +) + +if get_option('doc').enabled() or get_option('introspection').enabled() + doxygen_p = find_program('doxygen', version: '>= 1.9.0', required: true) +elif get_option('doc').auto() or get_option('introspection').auto() + doxygen_p = find_program('doxygen', version: '>= 1.9.0', required: false) +else + doxygen_p = disabler() endif -sphinx_c = run_command(sphinx_p, '--version') -breathe_c = run_command(breathe_p, '--version') -doxygen_c = run_command(doxygen_p, '--version') +sphinx_p = find_program('sphinx-build', + version: '>= 2.1.0', required: get_option('doc')) +gir_p = find_program('g-ir-scanner', required: get_option('introspection')) -sphinx_v = sphinx_c.stdout().split(' ')[1].strip() -breathe_v = breathe_c.stdout().split(' ')[2].strip() -doxygen_v = doxygen_c.stdout().strip() +build_doc = python_doc.found() and doxygen_p.found() and sphinx_p.found() +build_gir = python_gir.found() and doxygen_p.found() and gir_p.found() -if sphinx_v.version_compare('< 2.1.0') - error('Use at least sphinx version 2.1.0, found ' + sphinx_v) +# Run doxygen (common for docs and g-i) + +if build_doc or build_gir + doxy_wp_conf_data = configuration_data() + doxy_wp_conf_data.set('OUTPUT_DIR', meson.current_build_dir() / 'wp') + doxy_wp_conf_data.set('INPUT', meson.source_root() / 'lib' / 'wp') + doxyfile_wp = configure_file( + input: 'Doxyfile.in', + output: 'Doxyfile-wp', + configuration: doxy_wp_conf_data + ) + + doxyxml_wp_depfiles = [wp_lib_sources, wp_lib_headers] + doxyxml_wp = custom_target('doxyxml_wp', + command: [doxygen_p, doxyfile_wp], + depend_files: doxyxml_wp_depfiles, + output: 'wp', + build_by_default: true, + ) endif -if breathe_v.version_compare('< 4.11') - error('Use at least breathe version 4.11, found ' + breathe_v) +# Build documentation + +if build_doc + doxy_lua_input = [ + meson.source_root() / 'modules' / 'module-lua-scripting' / 'api.c', + meson.source_root() / 'modules' / 'module-lua-scripting' / 'pod.c', + ] + + doxy_lua_conf_data = configuration_data() + doxy_lua_conf_data.set('OUTPUT_DIR', meson.current_build_dir() / 'lua') + doxy_lua_conf_data.set('INPUT', ' \\\n '.join(doxy_lua_input)) + doxyfile_lua = configure_file( + input: 'Doxyfile.in', + output: 'Doxyfile-lua', + configuration: doxy_lua_conf_data + ) + + doxyxml_lua_depfiles = doxy_lua_input + doxyxml_lua = custom_target('doxyxml_lua', + command: [doxygen_p, doxyfile_lua], + depend_files: doxyxml_lua_depfiles, + output: 'lua', + build_by_default: true, + ) + + sphinx_files = files('index.rst') + subdir('api') + subdir('toc') + + sphinx_conf_data = configuration_data() + sphinx_conf_data.set('OUTDIR', meson.current_build_dir()) + sphinx_conf_data.set('VERSION', meson.project_version()) + sphinx_conf = configure_file( + input: 'conf.py.in', + output: 'conf.py', + configuration: sphinx_conf_data + ) + + custom_target('doc', + command: [sphinx_p, + '-q', # quiet + '-E', # rebuild from scratch + '-j', 'auto', # parallel build + '-d', '@PRIVATE_DIR@', # doctrees dir + '-c', '@OUTDIR@', # conf.py dir + '@CURRENT_SOURCE_DIR@', # source dir + '@OUTPUT@', # output dir + ], + depend_files: [ + sphinx_conf, sphinx_files, + doxyxml_wp_depfiles, doxyxml_lua_depfiles, + ], + depends: [doxyxml_wp, doxyxml_lua], + output: 'html', + install: true, + install_dir: get_option('datadir') / 'doc' / 'wireplumber', + build_by_default: true, + ) endif -if doxygen_v.version_compare('< 1.8') - error('Use at least doxygen version 1.8, found ' + doxygen_v) +# Build GObject introspection + +if build_gir + wp_gtkdoc_h = custom_target('wp_gtkdoc_h', + command: [python_gir, + '@CURRENT_SOURCE_DIR@/gen-api-gtkdoc.py', + '-o', '@OUTPUT@', + '@OUTDIR@/wp/xml', + ], + depends: [doxyxml_wp], + depend_files: doxyxml_wp_depfiles, + output: 'wp-gtkdoc.h', + build_by_default: true, + ) + + gnome.generate_gir(wp_lib, + namespace: 'Wp', + nsversion: wireplumber_api_version, + sources: [wpenums_c, wpenums_h, wp_gtkdoc_h], + includes: ['GLib-2.0', 'GObject-2.0', 'Gio-2.0'], + install: true, + ) endif - -if not build_gir - if get_option('doc').enabled() - error('Documentation enabled but introspection not built.') - endif -endif - -doxygen_database = meson.current_build_dir() + '/doxygen_doc' - -# modify the sphinx configuration and the breathe doxygen XML database -# to point where its being generated by doxygen -sphinx_conf_data = configuration_data() -sphinx_conf_data.set('BUILD_ROOT', doxygen_database) -sphinx_conf_data.set('VERSION', meson.project_version()) -sphinx_conf = configure_file( - input: 'conf.py.in', - output: 'conf.py', - configuration: sphinx_conf_data -) - -# build gir - -doxy_conf_data = configuration_data() -doxy_conf_data.set('SRC_ROOT', meson.source_root()) -doxy_conf_data.set('OUTPUT_DIR', doxygen_database) -doxygen_conf_wireplumber = configure_file( - input: 'doxyfile.in', - output: 'doxyfile', - configuration: doxy_conf_data -) - -dir_prefix = get_option('prefix') -dir_data = join_paths(dir_prefix, get_option('datadir')) - -script_data = configuration_data() -script_data.set('SRCDIR', meson.current_build_dir()) -script_data.set('OUTDIR', meson.current_build_dir() + '/docs') - -# Set a different directory for doctrees to avoid installing them -script_data.set('DOCTREES_DIR', meson.current_build_dir() + '/doctrees') - -script_data.set('SPHINX_CMD', sphinx_p.path()) - -script_doxy_sphinx = configure_file( - input: 'run_doxygen_sphinx.sh.in', - output: 'run_doxygen_sphinx.sh', - configuration: script_data -) - -# copy everything to build_dir, if you plan on adding other files in the top -# rootdir of sourcedir, please add them here as well, otherwise use 'toc/'s -# meson.build file - -sphinx_files = ['index.rst'] -foreach file : sphinx_files - configure_file(input: file, output: file, copy: true) -endforeach - -# and those in toc and api -subdir('toc') -subdir('api') - -sphinx_doc = custom_target( - 'breathe', - command: script_doxy_sphinx, - output: 'docs', - build_by_default: true, -) - -# we need this because we will have a stale 'docs' directory -# and this forces it to be rebuilt -docs = run_target( - 'docs', - command: script_doxy_sphinx, -) - -install_subdir( - sphinx_doc.full_path(), - install_dir: join_paths(dir_data, 'doc', 'wireplumber', 'html'), - exclude_files: '.buildinfo', - strip_directory: true, -) diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index dd98e2b1..00000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,5 +0,0 @@ -bs4 # BeautifulSoup! -lxml # We need the lxml backend for BeautifulSoup. -sphinx>=1.6.1 # 1.6 introduces logging API. -breathe # The directives used for documentation come from the excellent Breathe. -six # Primarily for Unicode string types diff --git a/docs/run_doxygen_sphinx.sh.in b/docs/run_doxygen_sphinx.sh.in deleted file mode 100755 index e7a7f9f1..00000000 --- a/docs/run_doxygen_sphinx.sh.in +++ /dev/null @@ -1,2 +0,0 @@ -#!/bin/sh -@SPHINX_CMD@ -E -Q -j auto -d @DOCTREES_DIR@ @SRCDIR@ @OUTDIR@ diff --git a/docs/run_gen_api.sh.in b/docs/run_gen_api.sh.in deleted file mode 100755 index 37051b13..00000000 --- a/docs/run_gen_api.sh.in +++ /dev/null @@ -1,2 +0,0 @@ -#!/bin/sh -@DOXYGEN_CMD@ @DOXYGEN_CONF@ && @PYTHON@ @GIR_PY_SCRIPT@ @XML_DIR@ -d @XML_DIR@ -o @OUTDIR@/wp-gtkdoc.h \ No newline at end of file diff --git a/docs/toc/lua_api/meson.build b/docs/toc/lua_api/meson.build index 22a68e06..b7d31d1b 100644 --- a/docs/toc/lua_api/meson.build +++ b/docs/toc/lua_api/meson.build @@ -1,5 +1,5 @@ # you need to add here any files you add to the toc directory as well -files = [ +sphinx_files += files( 'lua_core_api.rst', 'lua_client_api.rst', 'lua_endpoint_api.rst', @@ -15,8 +15,4 @@ files = [ 'lua_session_item_api.rst', 'lua_source_api.rst', 'lua_spa_device_api.rst', -] - -foreach file : files - configure_file(input: file, output: file, copy: true) -endforeach +) diff --git a/docs/toc/meson.build b/docs/toc/meson.build index 7942900a..ae458311 100644 --- a/docs/toc/meson.build +++ b/docs/toc/meson.build @@ -1,5 +1,5 @@ # you need to add here any files you add to the toc directory as well -files = [ +sphinx_files += files( 'installing-wireplumber.rst', 'running-wireplumber-daemon.rst', 'daemon-configuration.rst', @@ -8,10 +8,6 @@ files = [ 'community.rst', 'testing.rst', 'lua_api.rst' -] - -foreach file : files - configure_file(input: file, output: file, copy: true) -endforeach +) subdir('lua_api') diff --git a/lib/wp/meson.build b/lib/wp/meson.build index 2e5e491f..99bfd500 100644 --- a/lib/wp/meson.build +++ b/lib/wp/meson.build @@ -1,5 +1,4 @@ wp_lib_sources = files( - 'private/pipewire-object-mixin.c', 'client.c', 'component-loader.c', 'core.c', @@ -30,6 +29,10 @@ wp_lib_sources = files( 'wp.c', ) +wp_lib_priv_sources = files( + 'private/pipewire-object-mixin.c', +) + wp_lib_headers = files( 'client.h', 'component-loader.h', @@ -89,7 +92,7 @@ wpversion = configure_file( wp_gen_sources += [wpversion] wp_lib = library('wireplumber-' + wireplumber_api_version, - wp_lib_sources, wpenums_c, wpenums_h, wpversion, + wp_lib_sources, wp_lib_priv_sources, wpenums_c, wpenums_h, wpversion, c_args : [ '-D_GNU_SOURCE', '-DG_LOG_USE_STRUCTURED', @@ -105,44 +108,6 @@ wp_lib = library('wireplumber-' + wireplumber_api_version, version: meson.project_version(), ) -if build_gir - wp_gtkdoc_conf = configure_file( - input: '../../docs/gen-api-gtkdoc.py.in', - output: 'gen-api-gtkdoc.py', - copy: true - ) - - script_data = configuration_data() - script_data.set('PYTHON', 'python3') - script_data.set('OUTDIR', meson.current_build_dir()) - script_data.set('GIR_PY_SCRIPT', meson.current_build_dir() + '/gen-api-gtkdoc.py') - script_data.set('XML_DIR', meson.build_root() + '/docs/doxygen_doc/xml') - script_data.set('DOXYGEN_CONF', meson.build_root() + '/docs/doxyfile') - script_data.set('DOXYGEN_CMD', doxygen_p.path()) - - script_gen_api = configure_file( - input: '../../docs/run_gen_api.sh.in', - output: 'run_gen_api.sh', - configuration: script_data - ) - - wp_gtkdoc_h = custom_target( - 'gir', - command: script_gen_api, - output: 'wp-gtkdoc.h', - build_by_default: true, - ) - - wp_gir = gnome.generate_gir(wp_lib, - namespace: 'Wp', - nsversion: wireplumber_api_version, - sources: [wpenums_c, wpenums_h, wp_gtkdoc_h], - includes: ['GLib-2.0', 'GObject-2.0', 'Gio-2.0'], - install: true, - ) - wp_gen_sources += wp_gir -endif - wp_dep = declare_dependency( link_with: wp_lib, sources: wp_gen_sources, diff --git a/meson.build b/meson.build index 80cce931..a7099802 100644 --- a/meson.build +++ b/meson.build @@ -68,8 +68,6 @@ endif gnome = import('gnome') pkgconfig = import('pkgconfig') -gir = find_program('g-ir-scanner', required : get_option('introspection')) -build_gir = gir.found() wp_lib_include_dir = include_directories('lib') @@ -93,8 +91,6 @@ common_flags = [ ] add_project_arguments(cc.get_supported_arguments(common_flags), language: 'c') -doxygen_p = find_program('doxygen', required: get_option('doc')) - subdir('lib') subdir('docs') subdir('modules')