[pacman-dev] [PATCH 1/4] Remove DOXYGEN_MANS. New Doxyfile.in. Add 'make doxygen-*'.
Jeremy Heiner
scalaprotractor at gmail.com
Sat Dec 21 23:22:23 EST 2013
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
More information about the pacman-dev
mailing list