From bbf71b69ebf9d0d62a0af150a5c37d193b8159ad Mon Sep 17 00:00:00 2001 From: Jia Tan Date: Tue, 3 Jan 2023 20:37:30 +0800 Subject: [PATCH] Doxygen: Make Doxygen only produce liblzma API documentation by default. Doxygen is now configurable in autotools only with --enable-doxygen=[api|all]. The default is "api", which will only generate HTML output for liblzma API functions. The LaTex documentation output was also disabled. --- Doxyfile.in | 18 +++++++++--------- configure.ac | 39 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 48 insertions(+), 9 deletions(-) diff --git a/Doxyfile.in b/Doxyfile.in index 1364ff2d..e3653c8e 100644 --- a/Doxyfile.in +++ b/Doxyfile.in @@ -20,7 +20,7 @@ # The PROJECT_NAME tag is a single word (or a sequence of words surrounded # by quotes) that should identify the project. -PROJECT_NAME = "@PACKAGE_NAME@" +PROJECT_NAME = "@doxygen_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 @@ -96,7 +96,7 @@ ABBREVIATE_BRIEF = # Doxygen will generate a detailed section even if there is only a brief # description. -ALWAYS_DETAILED_SEC = YES +ALWAYS_DETAILED_SEC = NO # If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all # inherited members of a class in the documentation of that class as if those @@ -118,7 +118,7 @@ FULL_PATH_NAMES = YES # If left blank the directory from which doxygen is run is used as the # path to strip. -STRIP_FROM_PATH = @top_srcdir@/src +STRIP_FROM_PATH = @top_srcdir@/@doxygen_input_path@ # 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 @@ -220,18 +220,18 @@ EXTRACT_ALL = NO # If the EXTRACT_PRIVATE tag is set to YES all private members of a class # will be included in the documentation. -EXTRACT_PRIVATE = YES +EXTRACT_PRIVATE = @doxygen_extract_private@ # If the EXTRACT_STATIC tag is set to YES all static members of a file # will be included in the documentation. -EXTRACT_STATIC = YES +EXTRACT_STATIC = @doxygen_extract_private@ # If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) # defined locally in source files will be included in the documentation. # If set to NO only classes defined in header files are included. -EXTRACT_LOCAL_CLASSES = YES +EXTRACT_LOCAL_CLASSES = @doxygen_extract_private@ # If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all # undocumented members of documented classes, files or namespaces. @@ -439,7 +439,7 @@ WARN_LOGFILE = # directories like "/usr/src/myproject". Separate the files or directories # with spaces. -INPUT = @top_srcdir@/src +INPUT = @top_srcdir@/@doxygen_input_path@ # If the value of the INPUT tag contains directories, you can use the # FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp @@ -448,7 +448,7 @@ INPUT = @top_srcdir@/src # *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx # *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py -FILE_PATTERNS = *.h *.c +FILE_PATTERNS = *.c *.h # The RECURSIVE tag can be used to turn specify whether or not subdirectories # should be searched for input files as well. Possible values are YES and NO. @@ -724,7 +724,7 @@ TREEVIEW_WIDTH = 250 # If the GENERATE_LATEX tag is set to YES (the default) Doxygen will # generate Latex output. -GENERATE_LATEX = YES +GENERATE_LATEX = NO # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. # If a relative path is entered the value of OUTPUT_DIRECTORY will be diff --git a/configure.ac b/configure.ac index f005f19d..fd817909 100644 --- a/configure.ac +++ b/configure.ac @@ -520,6 +520,45 @@ AC_ARG_ENABLE([doc], [AS_HELP_STRING([--disable-doc], AM_CONDITIONAL([COND_DOC], [test x$enable_doc != xno]) +########### +# Doxygen # +########### + +# Doxygen can be enabled in two different modes: +# api - Only generate Doxygen html pages for liblzma API headers. +# all - Generate Doxygen html pages for every file. +# api mode is the default because the primary purpose for the doxygen +# documentation is to publicaly describe liblzma's API. The other html +# pages are only useful for those who want to understand or alter the +# internals of xz and liblzma. + +AC_ARG_ENABLE([doxygen], [AS_HELP_STRING([--enable-doxygen=SCOPE], + [Doxygen SCOPE can be `all`, or `api`. + The default is `api`, which will generate doxygen html + for liblzma API. The `all` option will generate doxygen + html for every .c and .h file.])], + [], [enable_doxygen=api]) +case $enable_doxygen in + api) + doxygen_project_name="liblzma ($PACKAGE_NAME)" + doxygen_extract_private=NO + doxygen_input_path=src/liblzma/api + ;; + all) + doxygen_project_name="$PACKAGE_NAME" + doxygen_extract_private=YES + doxygen_input_path=src + ;; + *) + AC_MSG_ERROR([--enable-doxygen only accepts `all` or `api]) + ;; +esac + +AC_SUBST([doxygen_project_name]) +AC_SUBST([doxygen_extract_private]) +AC_SUBST([doxygen_input_path]) + + ############## # Sandboxing # ##############