The man pages produced by doxygen never quite lived up to expectation, and it would now be very difficult to get them to fit in with the other man pages produced by asciidoc. So the doc/Makefile.am *_MANS settings are updated to only ever use the ASCIIDOC_MANS. The Doxyfile had grown quite stale, with settings from years back for which the current default values are better. It also specified 242 settings when most of them were at default values (and could thus be omitted - only 23 of the 242 actually accomplished anything). Also the hard-coded INPUT paths prevented VPATH builds. So a new, easier to understand, configured Doxyfile.in takes its place. Doxyfile.in no longer produces man pages, as they were never used. Instead it produces html. And it does so for all the pacman code, not just the libalpm API. Doxygen can optionally use the graphviz 'dot' app to produce more intricate graphs, if configure can find the program (unless --disable-graphviz is specified). The new 'make doxygen-run' and 'make doxygen-clean' targets are always available to invoke manually. If '--enable-doxygen' is passed to configure then 'make all' will invoke doxygen-run. All the doxygen output (the generated files, and logs of the stdout and stderr) is diverted to the 'doc/doxyout' subdir. The doxygen-clean target, which is always invoked by 'make clean', removes this subdir. Signed-off-by: Jeremy Heiner <ScalaProtractor at gmail.com> --- configure.ac | 26 ++++- doc/.gitignore | 3 +- doc/Doxyfile | 305 -------------------------------------------------------- doc/Doxyfile.in | 43 ++++++++ doc/Makefile.am | 27 +++-- 5 files changed, 82 insertions(+), 322 deletions(-) delete mode 100644 doc/Doxyfile create mode 100644 doc/Doxyfile.in diff --git a/configure.ac b/configure.ac index cfcc8d1..c088122 100644 --- a/configure.ac +++ b/configure.ac @@ -145,6 +145,11 @@ AC_ARG_ENABLE(doxygen, AS_HELP_STRING([--enable-doxygen], [build your own API docs via Doxygen]), [wantdoxygen=$enableval], [wantdoxygen=no]) +# Help line for graphviz (optionally used by doxygen) +AC_ARG_ENABLE(graphviz, + AS_HELP_STRING([--disable-graphviz], [prevent doxygen from using dot]), + [wantgraphviz=$enableval], [wantgraphviz=yes]) + # Help line for debug AC_ARG_ENABLE(debug, AS_HELP_STRING([--enable-debug], [enable debugging support]), @@ -381,7 +386,7 @@ AM_CONDITIONAL(WANT_DOC, test "x$wantdoc" = "xyes") # Check for doxygen support and status AC_CHECK_PROGS([DOXYGEN], [doxygen]) -AC_MSG_CHECKING([for doxygen]) +AC_MSG_CHECKING([whether 'make all' should 'make doxygen-run']) if test "x$wantdoxygen" = "xyes" ; then if test $DOXYGEN ; then AC_MSG_RESULT([yes]) @@ -396,6 +401,23 @@ else fi AM_CONDITIONAL(USE_DOXYGEN, test "x$usedoxygen" = "xyes") +# Optionally doxygen can use dot +AC_CHECK_PROGS([GRAPHVIZDOT], [dot]) +AC_MSG_CHECKING([whether doxygen should use graphviz]) +if test "x$wantgraphviz" = "xyes" ; then + if test $GRAPHVIZDOT ; then + AC_MSG_RESULT([yes]) + usegraphviz=yes + else + AC_MSG_RESULT([no, graphviz missing]) + usegraphviz=no + fi +else + AC_MSG_RESULT([no, disabled by configure]) + usegraphviz=no +fi +AC_SUBST(HAVE_DOT,`echo $usegraphviz | tr yesno YESNO`) + # Enable or disable debug code AC_MSG_CHECKING(for debug mode request) if test "x$debug" = "xyes" ; then @@ -498,6 +520,7 @@ src/pacman/po/Makefile.in src/util/Makefile scripts/Makefile scripts/po/Makefile.in +doc/Doxyfile doc/Makefile etc/Makefile test/pacman/Makefile @@ -551,6 +574,7 @@ ${PACKAGE_NAME}: Use OpenSSL : ${have_openssl} Run make in doc/ dir : ${wantdoc} ${asciidoc} Doxygen support : ${usedoxygen} + use graphviz dot : ${usegraphviz} debug support : ${debug} extra warning flags : ${warningflags} use git version : ${wantgitver} diff --git a/doc/.gitignore b/doc/.gitignore index ad496ce..7032f6e 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -16,5 +16,6 @@ asciidoc.css asciidoc.js *.html *.xml -man3 +Doxyfile +doxyout/ website.tar.gz diff --git a/doc/Doxyfile b/doc/Doxyfile deleted file mode 100644 index 4e64534..0000000 --- a/doc/Doxyfile +++ /dev/null @@ -1,305 +0,0 @@ -# Doxyfile 1.8.2 - -#--------------------------------------------------------------------------- -# Project related configuration options -#--------------------------------------------------------------------------- -DOXYFILE_ENCODING = UTF-8 -PROJECT_NAME = libalpm -PROJECT_NUMBER = -PROJECT_BRIEF = "Arch Linux Package Manager Library" -PROJECT_LOGO = -OUTPUT_DIRECTORY = ./ -CREATE_SUBDIRS = NO -OUTPUT_LANGUAGE = English -BRIEF_MEMBER_DESC = YES -REPEAT_BRIEF = YES -ABBREVIATE_BRIEF = "The $name class" \ - "The $name widget" \ - "The $name file" \ - is \ - provides \ - specifies \ - contains \ - represents \ - a \ - an \ - the -ALWAYS_DETAILED_SEC = YES -INLINE_INHERITED_MEMB = NO -FULL_PATH_NAMES = NO -STRIP_FROM_PATH = -STRIP_FROM_INC_PATH = -SHORT_NAMES = NO -JAVADOC_AUTOBRIEF = YES -QT_AUTOBRIEF = NO -MULTILINE_CPP_IS_BRIEF = NO -INHERIT_DOCS = YES -SEPARATE_MEMBER_PAGES = NO -TAB_SIZE = 4 -ALIASES = -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 = YES -DISTRIBUTE_GROUP_DOC = NO -SUBGROUPING = YES -INLINE_GROUPED_CLASSES = NO -INLINE_SIMPLE_STRUCTS = NO -TYPEDEF_HIDES_STRUCT = NO -SYMBOL_CACHE_SIZE = 0 -LOOKUP_CACHE_SIZE = 0 -#--------------------------------------------------------------------------- -# Build related configuration options -#--------------------------------------------------------------------------- -EXTRACT_ALL = NO -EXTRACT_PRIVATE = NO -EXTRACT_PACKAGE = NO -EXTRACT_STATIC = NO -EXTRACT_LOCAL_CLASSES = YES -EXTRACT_LOCAL_METHODS = NO -EXTRACT_ANON_NSPACES = NO -HIDE_UNDOC_MEMBERS = NO -HIDE_UNDOC_CLASSES = NO -HIDE_FRIEND_COMPOUNDS = NO -HIDE_IN_BODY_DOCS = YES -INTERNAL_DOCS = NO -CASE_SENSE_NAMES = YES -HIDE_SCOPE_NAMES = NO -SHOW_INCLUDE_FILES = YES -FORCE_LOCAL_INCLUDES = NO -INLINE_INFO = YES -SORT_MEMBER_DOCS = YES -SORT_BRIEF_DOCS = NO -SORT_MEMBERS_CTORS_1ST = NO -SORT_GROUP_NAMES = NO -SORT_BY_SCOPE_NAME = NO -STRICT_PROTO_MATCHING = NO -GENERATE_TODOLIST = YES -GENERATE_TESTLIST = YES -GENERATE_BUGLIST = YES -GENERATE_DEPRECATEDLIST= YES -ENABLED_SECTIONS = -MAX_INITIALIZER_LINES = 30 -SHOW_USED_FILES = YES -SHOW_FILES = YES -SHOW_NAMESPACES = YES -FILE_VERSION_FILTER = -LAYOUT_FILE = -CITE_BIB_FILES = -#--------------------------------------------------------------------------- -# configuration options related to warning and progress messages -#--------------------------------------------------------------------------- -QUIET = NO -WARNINGS = YES -WARN_IF_UNDOCUMENTED = YES -WARN_IF_DOC_ERROR = YES -WARN_NO_PARAMDOC = NO -WARN_FORMAT = "$file:$line: $text" -WARN_LOGFILE = -#--------------------------------------------------------------------------- -# configuration options related to the input files -#--------------------------------------------------------------------------- -INPUT = ../lib/libalpm/ -INPUT_ENCODING = UTF-8 -FILE_PATTERNS = -RECURSIVE = NO -EXCLUDE = -EXCLUDE_SYMLINKS = NO -EXCLUDE_PATTERNS = -EXCLUDE_SYMBOLS = -EXAMPLE_PATH = -EXAMPLE_PATTERNS = * -EXAMPLE_RECURSIVE = NO -IMAGE_PATH = -INPUT_FILTER = -FILTER_PATTERNS = -FILTER_SOURCE_FILES = NO -FILTER_SOURCE_PATTERNS = -#--------------------------------------------------------------------------- -# configuration options related to source browsing -#--------------------------------------------------------------------------- -SOURCE_BROWSER = NO -INLINE_SOURCES = NO -STRIP_CODE_COMMENTS = NO -REFERENCED_BY_RELATION = YES -REFERENCES_RELATION = YES -REFERENCES_LINK_SOURCE = YES -USE_HTAGS = NO -VERBATIM_HEADERS = YES -#--------------------------------------------------------------------------- -# configuration options related to the alphabetical class index -#--------------------------------------------------------------------------- -ALPHABETICAL_INDEX = NO -COLS_IN_ALPHA_INDEX = 5 -IGNORE_PREFIX = -#--------------------------------------------------------------------------- -# configuration options related to the HTML output -#--------------------------------------------------------------------------- -GENERATE_HTML = NO -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 = org.doxygen.Project -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 = 4 -TREEVIEW_WIDTH = 250 -EXT_LINKS_IN_WINDOW = NO -FORMULA_FONTSIZE = 10 -FORMULA_TRANSPARENT = YES -USE_MATHJAX = NO -MATHJAX_RELPATH = http://www.mathjax.org/mathjax -MATHJAX_EXTENSIONS = -SEARCHENGINE = NO -SERVER_BASED_SEARCH = NO -#--------------------------------------------------------------------------- -# configuration options related to the LaTeX output -#--------------------------------------------------------------------------- -GENERATE_LATEX = NO -LATEX_OUTPUT = latex -LATEX_CMD_NAME = latex -MAKEINDEX_CMD_NAME = makeindex -COMPACT_LATEX = NO -PAPER_TYPE = letter -EXTRA_PACKAGES = -LATEX_HEADER = -LATEX_FOOTER = -PDF_HYPERLINKS = NO -USE_PDFLATEX = NO -LATEX_BATCHMODE = NO -LATEX_HIDE_INDICES = NO -LATEX_SOURCE_CODE = NO -LATEX_BIB_STYLE = plain -#--------------------------------------------------------------------------- -# configuration options related to the RTF output -#--------------------------------------------------------------------------- -GENERATE_RTF = NO -RTF_OUTPUT = rtf -COMPACT_RTF = NO -RTF_HYPERLINKS = NO -RTF_STYLESHEET_FILE = -RTF_EXTENSIONS_FILE = -#--------------------------------------------------------------------------- -# configuration options related to the man page output -#--------------------------------------------------------------------------- -GENERATE_MAN = YES -MAN_OUTPUT = . -MAN_EXTENSION = .3 -MAN_LINKS = NO -#--------------------------------------------------------------------------- -# configuration options related to the XML output -#--------------------------------------------------------------------------- -GENERATE_XML = NO -XML_OUTPUT = xml -XML_SCHEMA = -XML_DTD = -XML_PROGRAMLISTING = YES -#--------------------------------------------------------------------------- -# configuration options for the AutoGen Definitions output -#--------------------------------------------------------------------------- -GENERATE_AUTOGEN_DEF = NO -#--------------------------------------------------------------------------- -# configuration options related to the Perl module output -#--------------------------------------------------------------------------- -GENERATE_PERLMOD = NO -PERLMOD_LATEX = NO -PERLMOD_PRETTY = YES -PERLMOD_MAKEVAR_PREFIX = -#--------------------------------------------------------------------------- -# Configuration options related to the preprocessor -#--------------------------------------------------------------------------- -ENABLE_PREPROCESSING = YES -MACRO_EXPANSION = YES -EXPAND_ONLY_PREDEF = YES -SEARCH_INCLUDES = YES -INCLUDE_PATH = ../.. -INCLUDE_FILE_PATTERNS = *.h -PREDEFINED = HAVE_CONFIG_H= \ - SYMHIDDEN= \ - SYMEXPORT= \ - HAVE_LIBARCHIVE \ - HAVE_LIBCURL \ - HAVE_LIBGPGME -EXPAND_AS_DEFINED = -SKIP_FUNCTION_MACROS = YES -#--------------------------------------------------------------------------- -# Configuration::additions related to external references -#--------------------------------------------------------------------------- -TAGFILES = -GENERATE_TAGFILE = -ALLEXTERNALS = NO -EXTERNAL_GROUPS = YES -PERL_PATH = /usr/bin/perl -#--------------------------------------------------------------------------- -# Configuration options related to the dot tool -#--------------------------------------------------------------------------- -CLASS_DIAGRAMS = NO -MSCGEN_PATH = -HIDE_UNDOC_RELATIONS = YES -HAVE_DOT = YES -DOT_NUM_THREADS = 0 -DOT_FONTNAME = Helvetica -DOT_FONTSIZE = 10 -DOT_FONTPATH = -CLASS_GRAPH = YES -COLLABORATION_GRAPH = YES -GROUP_GRAPHS = YES -UML_LOOK = NO -UML_LIMIT_NUM_FIELDS = 10 -TEMPLATE_RELATIONS = NO -INCLUDE_GRAPH = YES -INCLUDED_BY_GRAPH = YES -CALL_GRAPH = NO -CALLER_GRAPH = NO -GRAPHICAL_HIERARCHY = YES -DIRECTORY_GRAPH = YES -DOT_IMAGE_FORMAT = png -INTERACTIVE_SVG = NO -DOT_PATH = -DOTFILE_DIRS = -MSCFILE_DIRS = -DOT_GRAPH_MAX_NODES = 50 -MAX_DOT_GRAPH_DEPTH = 3 -DOT_TRANSPARENT = NO -DOT_MULTI_TARGETS = NO -GENERATE_LEGEND = YES -DOT_CLEANUP = YES diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in new file mode 100644 index 0000000..6250ec5 --- /dev/null +++ b/doc/Doxyfile.in @@ -0,0 +1,43 @@ + +# @configure_input@ + +PROJECT_NAME = @PACKAGE_NAME@ +PROJECT_NUMBER = @PACKAGE_VERSION@ +PROJECT_BRIEF = "Arch Linux Package Manager" + +INPUT = @top_srcdir@/lib/libalpm \ + @top_srcdir@/src/pacman \ + @top_srcdir@/src/util \ + @top_srcdir@/test/pacman + +STRIP_FROM_PATH = @top_srcdir@/ + +OPTIMIZE_OUTPUT_FOR_C = YES +TYPEDEF_HIDES_STRUCT = YES +JAVADOC_AUTOBRIEF = YES + +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = YES + +PREDEFINED = HAVE_LIBCURL HAVE_LIBGPGME SYMEXPORT= + +EXTRACT_ALL = YES +EXTRACT_PRIVATE = YES +EXTRACT_STATIC = YES +INTERNAL_DOCS = YES + +OUTPUT_DIRECTORY = doxyout + +GENERATE_LATEX = NO + +GENERATE_HTML = YES +DISABLE_INDEX = YES +GENERATE_TREEVIEW = YES +HTML_DYNAMIC_SECTIONS = YES + +SOURCE_BROWSER = YES +REFERENCES_RELATION = YES +REFERENCED_BY_RELATION = YES + +HAVE_DOT = @HAVE_DOT@ + diff --git a/doc/Makefile.am b/doc/Makefile.am index cb01255..7f284b8 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,7 +1,6 @@ # We have to do some funny stuff here with the manpages. In order to ensure # a dist tarball doesn't get put out there without manpages, we keep those -# files listed in EXTRA_DIST no matter what. However, we only add them to -# man_MANS if --enable-asciidoc and/or --enable-doxygen are used. +# files listed in EXTRA_DIST no matter what. ASCIIDOC_MANS = \ pacman.8 \ @@ -17,8 +16,6 @@ ASCIIDOC_MANS = \ pacman.conf.5 \ libalpm.3 -DOXYGEN_MANS = $(wildcard man3/*.3) - HTML_MANPAGES = \ pacman.8.html \ makepkg.8.html \ @@ -63,9 +60,7 @@ EXTRA_DIST = \ index.txt \ submitting-patches.txt \ translation-help.txt \ - Doxyfile \ - $(ASCIIDOC_MANS) \ - $(DOXYGEN_MANS) + $(ASCIIDOC_MANS) # Files that should be removed, but which Automake does not know. MOSTLYCLEANFILES = *.xml $(ASCIIDOC_MANS) $(HTML_DOCS) repo-remove.8 website.tar.gz @@ -82,23 +77,25 @@ else REAL_PACKAGE_VERSION = $(PACKAGE_VERSION) endif -man_MANS = dist_man_MANS = $(ASCIIDOC_MANS) if USE_DOXYGEN -man_MANS += $(DOXYGEN_MANS) - -all-local: doxygen.in - -doxygen.in: - $(DOXYGEN) $(srcdir)/Doxyfile +all-local: doxygen-run endif +doxygen-run: + mkdir -p doxyout + doxygen 2>&1 >doxyout/doxygen-run.stdout | \ + tee doxyout/doxygen-run.stderr + +clean-local: doxygen-clean +doxygen-clean: + -rm -rf doxyout html: $(HTML_DOCS) website: website.tar.gz -.PHONY: html website +.PHONY: html website doxygen-run doxygen-clean website.tar.gz: html $(AM_V_GEN)bsdtar czf $@ $(HTML_DOCS) \ -- 1.8.5.2