[pacman-dev] [PATCH 1/4] Remove DOXYGEN_MANS. New Doxyfile.in. Add 'make doxygen-*'.
Allan McRae
allan at archlinux.org
Sat Dec 28 00:16:15 EST 2013
On 22/12/13 14:22, Jeremy Heiner wrote:
> 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.
Fine.
> 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.
The Doxyfile file is generated automatically by "doxygen -s -g" and is
updated automatically with "doxygen -s -u". I have never seen a project
using a reduced version of that file with just the non-defaults in it.
Also, having all options explicitly stated means that people building
the documentation using a known good options set. I'll need some
convincing why this is a good approach.
> 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).
Fine.
> 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.
I'm not convinced about keeping the logs of stdout and stderr in that
directory for two reasons:
1) We do not do that for any other part of the build
2) It means we need to clean that directory before dumping on a webserver.
Also, not having stdout/stderr interlaced can remove context for the errors.
I think this should be a series of patches:
1) Stop generating libalpm.3
2) Update Doxyfile and move to Doxyfile.in
3) Add configure support for --disable-graphviz
Extra patch:
4) PROJECT_NUMBER = @LIB_VERSION@ (or @PACKAGE_VERSION@ ???)
> 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'])
I do not understand this change. It is inconsistent with every other
message for checking that autoconf does. It also (slightly) masks that
missing doxygen is the reason for failure.
> 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@
> +
When I compare a default Doxyfile (made from doxygen -s -g) and an
updated version of the one in doc/ (doxygen -s -u), there seem to have
been a number of other settings in the doc/Doxygen that are non default
that are not transferred here.
> 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 | \
s/doxygen/$(DOXYGEN)/
> + 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) \
>
More information about the pacman-dev
mailing list