From 59d9c2d83db722599d612f4339d9d8405f0c13e7 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Wed, 25 Jan 2017 16:38:02 +0000 Subject: [PATCH] Generate the Epoxy API reference using Doxygen The build is conditional on: * using the Meson build * passing the `-Denable-docs=true` configuration switch * having `doxygen` installed Currently, the generated HTML is kind of empty, but it works. --- doc/Doxyfile.in | 206 ++++++++++++++++++++++++++++++++++++++++++++++ doc/meson.build | 32 +++++++ meson.build | 9 ++ meson_options.txt | 3 + 4 files changed, 250 insertions(+) create mode 100644 doc/Doxyfile.in create mode 100644 doc/meson.build create mode 100644 meson_options.txt diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in new file mode 100644 index 0000000..57a680f --- /dev/null +++ b/doc/Doxyfile.in @@ -0,0 +1,206 @@ +DOXYFILE_ENCODING = UTF-8 +PROJECT_NAME = @PACKAGE_NAME@ +PROJECT_NUMBER = @PACKAGE_VERSION@ +PROJECT_BRIEF = +PROJECT_LOGO = +OUTPUT_DIRECTORY = doc +CREATE_SUBDIRS = NO +ALLOW_UNICODE_NAMES = YES +OUTPUT_LANGUAGE = English +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ABBREVIATE_BRIEF = +ALWAYS_DETAILED_SEC = NO +INLINE_INHERITED_MEMB = NO +FULL_PATH_NAMES = YES +STRIP_FROM_PATH = "@top_srcdir@/include" "@top_builddir@/include" + +SHORT_NAMES = NO +JAVADOC_AUTOBRIEF = YES +QT_AUTOBRIEF = NO +MULTILINE_CPP_IS_BRIEF = NO +INHERIT_DOCS = YES +SEPARATE_MEMBER_PAGES = NO +TAB_SIZE = 8 +ALIASES = "newin{2}=\xrefitem since_\1_\2 \"Since @PACKAGE_NAME@ \1.\2\" \"New API in @PACKAGE_NAME@ \1.\2\"" +TCL_SUBST = +OPTIMIZE_OUTPUT_FOR_C = YES +OPTIMIZE_OUTPUT_JAVA = NO +OPTIMIZE_FOR_FORTRAN = NO +OPTIMIZE_OUTPUT_VHDL = NO +EXTENSION_MAPPING = +MARKDOWN_SUPPORT = YES +AUTOLINK_SUPPORT = YES +BUILTIN_STL_SUPPORT = NO +CPP_CLI_SUPPORT = NO +SIP_SUPPORT = NO +IDL_PROPERTY_SUPPORT = NO +DISTRIBUTE_GROUP_DOC = NO +GROUP_NESTED_COMPOUNDS = NO +SUBGROUPING = YES +INLINE_GROUPED_CLASSES = NO +INLINE_SIMPLE_STRUCTS = NO +TYPEDEF_HIDES_STRUCT = NO +LOOKUP_CACHE_SIZE = 0 + +EXTRACT_ALL = YES +EXTRACT_PRIVATE = NO +EXTRACT_PACKAGE = NO +EXTRACT_STATIC = NO +EXTRACT_LOCAL_CLASSES = NO +EXTRACT_LOCAL_METHODS = NO +EXTRACT_ANON_NSPACES = NO +HIDE_UNDOC_MEMBERS = YES +HIDE_UNDOC_CLASSES = YES +HIDE_FRIEND_COMPOUNDS = YES +HIDE_IN_BODY_DOCS = YES +INTERNAL_DOCS = NO +CASE_SENSE_NAMES = YES +HIDE_SCOPE_NAMES = NO +HIDE_COMPOUND_REFERENCE= NO +SHOW_INCLUDE_FILES = YES +SHOW_GROUPED_MEMB_INC = NO +FORCE_LOCAL_INCLUDES = NO +INLINE_INFO = YES +SORT_MEMBER_DOCS = YES +SORT_BRIEF_DOCS = NO +SORT_MEMBERS_CTORS_1ST = YES +SORT_GROUP_NAMES = YES +SORT_BY_SCOPE_NAME = YES +STRICT_PROTO_MATCHING = NO +GENERATE_TODOLIST = YES +GENERATE_TESTLIST = NO +GENERATE_BUGLIST = YES +GENERATE_DEPRECATEDLIST= YES +ENABLED_SECTIONS = +MAX_INITIALIZER_LINES = 2 +SHOW_USED_FILES = YES +SHOW_FILES = YES +SHOW_NAMESPACES = NO +FILE_VERSION_FILTER = +LAYOUT_FILE = +CITE_BIB_FILES = + +QUIET = YES +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_NO_PARAMDOC = YES +WARN_AS_ERROR = NO +WARN_FORMAT = "$file:$line: $text" +WARN_LOGFILE = doc/doxygen.log + +INPUT = "@top_srcdir@/include/epoxy" "@top_srcdir@/src" +INPUT_ENCODING = UTF-8 +FILE_PATTERNS = "*.h" "*.c" +RECURSIVE = NO +EXCLUDE = "@top_srcdir@/src/gen_dispatch.py" +EXCLUDE_SYMLINKS = YES +EXCLUDE_PATTERNS = +EXCLUDE_SYMBOLS = _* GLAPI* KHRONOS_* APIENTRY* GLX* wgl* +EXAMPLE_PATH = +EXAMPLE_PATTERNS = +EXAMPLE_RECURSIVE = NO +IMAGE_PATH = +INPUT_FILTER = +FILTER_PATTERNS = +FILTER_SOURCE_FILES = NO +FILTER_SOURCE_PATTERNS = +USE_MDFILE_AS_MAINPAGE = + +SOURCE_BROWSER = NO +INLINE_SOURCES = NO +STRIP_CODE_COMMENTS = YES +REFERENCED_BY_RELATION = NO +REFERENCES_RELATION = NO +REFERENCES_LINK_SOURCE = YES +SOURCE_TOOLTIPS = YES +USE_HTAGS = NO +VERBATIM_HEADERS = NO + +ALPHABETICAL_INDEX = YES +COLS_IN_ALPHA_INDEX = 3 +IGNORE_PREFIX = "epoxy" + +GENERATE_HTML = YES +HTML_OUTPUT = html +HTML_FILE_EXTENSION = .html +HTML_HEADER = +HTML_FOOTER = +HTML_STYLESHEET = +HTML_EXTRA_STYLESHEET = +HTML_EXTRA_FILES = +HTML_COLORSTYLE_HUE = 220 +HTML_COLORSTYLE_SAT = 100 +HTML_COLORSTYLE_GAMMA = 80 +HTML_TIMESTAMP = YES +HTML_DYNAMIC_SECTIONS = NO +HTML_INDEX_NUM_ENTRIES = 100 +GENERATE_DOCSET = NO +DOCSET_FEEDNAME = "Doxygen generated docs" +DOCSET_BUNDLE_ID = org.doxygen.Project +DOCSET_PUBLISHER_ID = org.doxygen.Publisher +DOCSET_PUBLISHER_NAME = Publisher +GENERATE_HTMLHELP = NO +CHM_FILE = +HHC_LOCATION = +GENERATE_CHI = NO +CHM_INDEX_ENCODING = +BINARY_TOC = NO +TOC_EXPAND = NO +GENERATE_QHP = NO +QCH_FILE = +QHP_NAMESPACE = +QHP_VIRTUAL_FOLDER = doc +QHP_CUST_FILTER_NAME = +QHP_CUST_FILTER_ATTRS = +QHP_SECT_FILTER_ATTRS = +QHG_LOCATION = +GENERATE_ECLIPSEHELP = NO +ECLIPSE_DOC_ID = org.doxygen.Project +DISABLE_INDEX = NO +GENERATE_TREEVIEW = NO +ENUM_VALUES_PER_LINE = 1 +TREEVIEW_WIDTH = 250 +EXT_LINKS_IN_WINDOW = NO +FORMULA_FONTSIZE = 10 +FORMULA_TRANSPARENT = YES +USE_MATHJAX = NO +MATHJAX_FORMAT = HTML-CSS +MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest +MATHJAX_EXTENSIONS = +MATHJAX_CODEFILE = +SEARCHENGINE = NO +SERVER_BASED_SEARCH = NO +EXTERNAL_SEARCH = NO +SEARCHENGINE_URL = +SEARCHDATA_FILE = +EXTERNAL_SEARCH_ID = +EXTRA_SEARCH_MAPPINGS = + +GENERATE_LATEX = NO +GENERATE_RTF = NO +GENERATE_MAN = NO +GENERATE_XML = NO +GENERATE_DOCBOOK = NO +GENERATE_AUTOGEN_DEF = NO +GENERATE_PERLMOD = NO + +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = YES +SEARCH_INCLUDES = YES +INCLUDE_PATH = "@top_srcdir@/include" \ + "@top_builddir@/include" +INCLUDE_FILE_PATTERNS = *.h +PREDEFINED = DOXYGEN_SHOULD_SKIP_THIS \ + "PUBLIC=" \ + "EPOXY_PUBLIC=" \ + "EPOXY_IMPORTEXPORT=" +EXPAND_AS_DEFINED = +SKIP_FUNCTION_MACROS = YES + +CLASS_DIAGRAMS = NO +ALLEXTERNALS = NO +EXTERNAL_GROUPS = NO +EXTERNAL_PAGES = NO diff --git a/doc/meson.build b/doc/meson.build new file mode 100644 index 0000000..b99bce3 --- /dev/null +++ b/doc/meson.build @@ -0,0 +1,32 @@ +doc_sources = [ + join_paths(meson.source_root(), 'include/epoxy/gl.h'), + join_paths(meson.source_root(), 'include/epoxy/egl.h'), + join_paths(meson.source_root(), 'include/epoxy/glx.h'), + join_paths(meson.source_root(), 'include/epoxy/wgl.h'), + + join_paths(meson.source_root(), 'src/dispatch_common.c'), + join_paths(meson.source_root(), 'src/dispatch_egl.c'), + join_paths(meson.source_root(), 'src/dispatch_glx.c'), + join_paths(meson.source_root(), 'src/dispatch_wgl.c'), +] + +doxyfile_conf = configuration_data() +doxyfile_conf.set('PACKAGE_NAME', meson.project_name()) +doxyfile_conf.set('PACKAGE_VERSION', meson.project_version()) +doxyfile_conf.set('top_srcdir', meson.source_root()) +doxyfile_conf.set('top_builddir', meson.build_root()) +doxyfile_conf.set('DOC_SOURCES', ' '.join(doc_sources)) + +doxyfile = configure_file(input: 'Doxyfile.in', + output: 'Doxyfile', + configuration: doxyfile_conf, + install: false) + +docdir = join_paths(epoxy_datadir, 'doc') + +html_target = custom_target('epoxy-docs', + input: [ doxyfile ] + doc_sources, + output: [ 'html' ], + command: [ doxygen, doxyfile ], + install: true, + install_dir: join_paths(docdir, 'epoxy')) diff --git a/meson.build b/meson.build index c75622c..c8e45cd 100644 --- a/meson.build +++ b/meson.build @@ -170,3 +170,12 @@ libepoxy_inc = [ subdir('include/epoxy') subdir('src') subdir('test') + +if get_option('enable-docs') + doxygen = find_program('doxygen', required: false) + if doxygen.found() + subdir('doc') + else + message('Documentation disabled without doxygen') + endif +endif diff --git a/meson_options.txt b/meson_options.txt new file mode 100644 index 0000000..4eaa634 --- /dev/null +++ b/meson_options.txt @@ -0,0 +1,3 @@ +option('enable-docs', + type: 'boolean', value: false, + description: 'Enable generating the Epoxy API reference (depends on Doxygen)')