Skip to content

GitLab

Commit f7eb9a04 authored by Karl Wette's avatar Karl Wette
Browse files

Doxygen: build separate documentation for each LAL library 

- Doxygen build system moved to per-library doxygen/ directories.
- Minimum required Doxygen version set to 1.8.1.2 (Wheezy).
- Doxygen layout from v1.8.1.2, configuration from 1.8.5 (SL7).
- Support local MathJax installation with --with-mathjax option.
- Drop support for unwieldy PDF documentation.
- Doxygenise last vestiges of LaTeX documentation in LALApps.
- Unused documentation files moved to per-library attic/ directories.
- Fix Doxygen warnings, and enforce Doxygen builds without warnings.
Original: 7bffd0bf027b06a4b0cc044748a2ae3729739b77
parent 8f035ab4
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 970 additions and 9948 deletions

Too many changes to show.

To preserve performance only 1000 of 1000+ files are displayed.
Plain diff Email patch
doxygen/LaTeX2doxygen.pl → attic/lal/LaTeX2doxygen.pl
View file @ f7eb9a04
......@@ -21,35 +21,55 @@ for my $texfname (@ARGV) {
# check that Doxygen file does not exist
die "File '$doxyfname' already exists!" if (-f $doxyfname);
# open files
# open input file
open TEX, "<$texfname" or die "Could not open '$texfname'!: $!";
open DOXY, ">$doxyfname" or die "Could not open '$doxyfname'!: $!";
# copy header of LaTeX file verbatim to doxygen file
# slurp the header and contents of the LaTeX document
my $header = "";
while (<TEX>) {
last if $_ =~ /^ *\\begin{document}/;
print DOXY "// $_";
$header .= $_;
}
# slurp the contents of the LaTeX document
my $latex = "";
my $contents = "";
while (<TEX>) {
last if $_ =~ /^ *\\end{document}/;
$latex .= $_;
$contents .= $_;
}
close TEX;
# if contents is empty, use header (LaTeX document is a fragment)
if ($contents eq "") {
$contents = $header;
$header = "";
}
# convert to Doxygen
my $doxygen = toDoxygen($latex);
my $doxygen = toDoxygen($contents);
# write to output file
print DOXY "/**\n\\page pagename\n\n$doxygen\n*/\n";
open DOXY, ">$doxyfname" or die "Could not open '$doxyfname'!: $!";
if ($header ne "") {
print DOXY "/*\n";
for my $line (split /\n/, $header) {
$line = " * $line";
$line =~ s/\s*$//;
print DOXY "$line\n";
}
print DOXY " */\n\n";
}
print DOXY "/**\n * \\page $texfname\n";
for my $line (split /\n/, $doxygen) {
$line = " * $line";
$line =~ s/\s*$//;
print DOXY "$line\n";
}
print DOXY " */\n";
close DOXY;
}
exit(0);
# convert LaTeX to doxygen documentation
sub toDoxygen {
......@@ -58,6 +78,9 @@ sub toDoxygen {
# regex for non-line-breaking whitespace
my $n = "[^\\S\n]";
# get rid of LaTeX comments
$text =~ s!([^%]?)%.*$!\1!mg;
# get rid of LSD LaTeX and Verbatim tags
$text =~ s!</?lal(?:LaTeX|Verbatim)[^>]*?>!!sg;
......@@ -109,19 +132,19 @@ sub toDoxygen {
# two arguments
$text =~ s!\\(?:
providecommand
)$bbr$bbr!!mgx;
)\*?$bbr$bbr!!mgx;
# two arguments, first optional
#$text =~ s!\\(?:
#idx
#)$bbk?$bbr!!mgx;
$text =~ s!\\(?:
idx
)\*?$bbk?$bbr!!mgx;
# one argument
$text =~ s!\\(?:
vfill|vspace
)$bbr!!mgx;
vfill|vspace|hspace
)\*?$bbr!!mgx;
# no arguments
$text =~ s!\\(?:
footnotesize|medskip|newpage|noindent
)$n*!!mgx;
footnotesize|medskip|newpage|noindent|newline|leavevmode
)\*?$n*!!mgx;
# remove these LaTeX commands but leave argument:
# one argument
......@@ -134,6 +157,9 @@ sub toDoxygen {
figure|table
)}!(MANUAL INTERVENTION $1 $2)!mgpx;
# convert verbatim commands
$text =~ s!\\verb(.)(.+?)\1!\\texttt{$2}!mg;
# convert formulae
$text =~ s!\$\$(.+?)\$\$!\\f[$1\\f]!sg;
$text =~ s!\$(.+?)\$!\\f\$$1\\f\$!sg;
......@@ -156,33 +182,43 @@ sub toDoxygen {
# convert descriptions
sub desc {
my ($text) = @_;
$text =~ s{\\begin$n*{description}(?<LIST>.*?)\\end$n*{description}}{
$_ = $+{LIST};
$text =~ s{DOXY(\((?:[^()]++|(?1))*\))}{
$_ = $1;
s/^\(*//;
s/\)*$//;
$_ = desc($_);
while (/\\item\[/) {
s!\\item$wbbk(?<TEXT>.*?)(?<END>\n*\\item\[|\Z)!<dt>$1</dt><dd>$+{TEXT}</dd>$+{END}!sx;
}
'<dl>' . desc($_) . '</dl>'
'<dl>' . $_ . '</dl>'
}sge;
return $text;
}
$text =~ s!\\begin$n*{(description|entry)}!DOXY(!mg;
$text =~ s!\\end$n*{(description|entry)}!)!mg;
$text = desc($text);
# convert numbered and unnumbered lists
sub list {
my ($text) = @_;
$text =~ s{\\begin$n*{(?<ENV>enumerate|itemize)}(?<LIST>.*?)\\end$n*{\k<ENV>}}{
my $e = $+{ENV};
$_ = $+{LIST};
$e =~ s!enumerate!ol!;
$e =~ s!itemize!ul!;
my ($text, $e) = @_;
$text =~ s{DOXY(\((?:[^()]++|(?1))*\))}{
$_ = $1;
s/^\(*//;
s/\)*$//;
$_ = list($_, $e);
while (/\\item/) {
s!\\item(?<TEXT>.*?)(?<END>\n*\\item|\Z)!<li>$+{TEXT}</li>$+{END}!sx;
}
"<$e>" . list($_) . "</$e>"
"<$e>" . $_ . "</$e>"
}sge;
return $text;
}
$text = list($text);
$text =~ s!\\begin{(enumerate)}!DOXY(!g;
$text =~ s!\\end{(enumerate)}!)!g;
$text = list($text, "ol");
$text =~ s!\\begin{(itemize)}!DOXY(!g;
$text =~ s!\\end{(itemize)}!)!g;
$text = list($text, "ul");
# convert tables
$text =~ s{\\begin$n*{tabular}$bbr?(?<TABLE>.*?)\\end$n*{tabular}}{
......@@ -203,9 +239,9 @@ sub toDoxygen {
# replace formatting commands
$text =~ s!\{\\(tt|it|rm|sc|sl|bf|sf)$n+!\\text$1\{!sg;
$text =~ s!\\verb(.)(.+?)\1!\\texttt{$2}!mg;
$text =~ s!\\emph!\\textit!sg;
$text =~ s!\\text(?:sc|sl|bf|sf)!\\texttt!sg;
$text =~ s!\\f\$\\text(tt|it)\s*$bbr\\f\$!\\text\1\2!sg;
$text =~ s{\\text(tt|it)\s*$wbbr}{
my $e = $1;
$_ = $2;
......@@ -214,6 +250,9 @@ sub toDoxygen {
($e eq 'tt' ? "\\c $_" : "\\e $_" ) :
($e eq 'tt' ? "<tt>$_</tt>" : "<em>$_</em>" )
}sge;
$text =~ s!\\prog$wbbr!<tt>\1</tt>!sg;
$text =~ s!\\option$wbbr!<tt>\1</tt>!sg;
$text =~ s!\\parm$wbbr!<i>\1</i>!sg;
# special treatment of 'Synopsis/Prototypes/Description/Uses/Algorithm/Notes' sections: turn into 'heading'
$text =~ s!\\(?:sub)*section\*?{(Synopsis|Description|Prototypes|Algorithm|Notes|Uses|Usage)}!\n### $1 ###\n!g;
......@@ -245,9 +284,9 @@ sub toDoxygen {
## intelligent guess about equation references
$text =~ s!([Ee]qs?|[Ee]quations?)[.\\~]*\\TODOref!\1.\\eqref!mg;
## intelligent guess about figure references
$text =~ s!([Ff]igs?|[Ff]igures?)[.\\~]*\\TODOref!\1.\\figref!mg;
$text =~ s!([Ff]igs?|[Ff]igures?)[.\\~]*\\TODOref$wbbr!\\ref \2 "this figure"!mg;
## intelligent guess about table references
$text =~ s!([Tt]ab?|[Tt]ables?)[.\\~]*\\TODOref!\1.\\tableref!mg;
$text =~ s!([Tt]ab?|[Tt]ables?)[.\\~]*\\TODOref$wbbr!\\ref \2 "this table"!mg;
# replace probable filenames with references
$text =~ s!<tt>(.*?\.[ch])</tt>!\\ref \1!mg;
......@@ -301,6 +340,9 @@ sub toDoxygen {
# remove trailing whitespace
$text =~ s!$n*$!!mg;
# remove excess blank lines
$text =~ s!\n\n\n*!\n\n!g;
return $text;
}
......@@ -314,4 +356,6 @@ LaTeX2doxygen "file.tex" ...
Converts each LaTeX "file.tex" to Doxygen, which is written to "file.dox"
Authors: Karl Wette, Reinhard Prix
=cut
doxygen/src/merger.eps → attic/lal/merger.eps
View file @ f7eb9a04
%!PS-Adobe-3.0 EPSF-3.0
%%LanguageLevel: 3
%!PS-Adobe-2.0 EPSF-2.0
%%Title: merger.ps
%%Creator: timeline.c
%%CreationDate: Tue Jul 11 15:32:01 2000
%%Pages: 1
%%Orientation: Portrait
%%BoundingBox: 69 49 543 557
%%HiResBoundingBox: 69.930 49.991 542.910 556.911
%%BoundingBox: 79 40 533 550
%%BeginSetup
%%EndSetup
%%EndComments
......@@ -52,9 +51,7 @@ exch cos -3 mul 1.5 sub currentlinewidth mul rlineto
/shear { % Draws arrows indicating tidal shear. Takes two arguments:
% a vertical offset, and a rotation angle.
gsave exch dup 0 exch translate
600 div 1 add dup scale
1 0.389418 scale rotate
gsave exch 0 exch translate 1 0.389418 scale rotate
120 120 112 180 270 inarrowarc
-120 120 112 360 270 inarrowarcn
-120 -120 112 0 90 inarrowarc
......@@ -115,24 +112,4 @@ gsave 1 0.389418 scale
0 0 276 110 200 outarrowarc
grestore
% Draw title
/title (LALSuite Doxygen) def
/Helvetica-Bold findfont 72 scalefont setfont
/titlewidth { title stringwidth pop } def
0 titlewidth sub 2 div 380 moveto
title false charpath
gsave
clip <<
/ShadingType 2 /ColorSpace /DeviceRGB /Coords [0 380 0 380 72 add]
/Function << /FunctionType 2 /Domain [0 1] /C0 [1 1 1] /C1 [0 0.8 1] /N 1 >>
>> shfill
grestore
gsave
1 0 0 setrgbcolor
clip 400 -20 shear
grestore
0 0 0 setrgbcolor
1 setlinewidth
stroke
showpage
configure.ac
View file @ f7eb9a04
......@@ -11,7 +11,6 @@ LALSUITE_DISTCHECK_CONFIGURE_FLAGS
# provide LAL library enable/disable options
LALSUITE_ENABLE_ALL_LAL
doxygen=true
lal=true
LALSUITE_ENABLE_LALFRAME
LALSUITE_ENABLE_LALMETAIO
......@@ -44,7 +43,8 @@ AC_DEFUN([lalsuite_config_subdir],[
uppercase[]_DATA_PATH="${lalsuite_top_srcdir}/lowercase/test"
uppercase[]_OCTAVE_PATH="${lalsuite_abs_top_builddir}/lowercase/octave"
uppercase[]_PYTHON_PATH="${lalsuite_abs_top_builddir}/lowercase/python"
export uppercase[]_LIBS uppercase[]_CFLAGS
uppercase[]_DOCDIR="${datarootdir}/doc/lowercase"
export uppercase[]_LIBS uppercase[]_CFLAGS uppercase[]_DOCDIR
export uppercase[]_DATA_PATH uppercase[]_OCTAVE_PATH uppercase[]_PYTHON_PATH
# configure $1
......@@ -61,23 +61,24 @@ AC_DEFUN([lalsuite_config_subdir],[
m4_popdef([uppercase])
])
# doxygen, lal, and lalsupport are always configured
AC_CONFIG_SUBDIRS(doxygen)
# lal and lalsupport are always configured
AC_CONFIG_SUBDIRS(lal)
LAL_LIBS="${lalsuite_abs_top_builddir}/lal/lib/lal/liblal.la"
LAL_CFLAGS="-I${lalsuite_abs_top_builddir}/lal/include"
LAL_DATA_PATH="${lalsuite_top_srcdir}/lal/test"
LAL_OCTAVE_PATH="${lalsuite_abs_top_builddir}/lal/octave"
LAL_PYTHON_PATH="${lalsuite_abs_top_builddir}/lal/python"
LAL_DOCDIR="${datarootdir}/doc/lal"
LALSUPPORT_LIBS="${lalsuite_abs_top_builddir}/lal/lib/lalsupport/src/liblalsupport.la"
LALSUPPORT_CFLAGS="-I${lalsuite_abs_top_builddir}/lal/include"
LALSUPPORT_DATA_PATH="${LAL_DATA_PATH}"
LALSUPPORT_OCTAVE_PATH="${LAL_OCTAVE_PATH}"
LALSUPPORT_PYTHON_PATH="${LAL_PYTHON_PATH}"
LALSUPPORT_DOCDIR="${datarootdir}/doc/lal"
LALSUITE_BUILD="true"
export LALSUITE_BUILD
export LAL_LIBS LAL_CFLAGS LAL_DATA_PATH LAL_OCTAVE_PATH LAL_PYTHON_PATH
export LALSUPPORT_LIBS LALSUPPORT_CFLAGS LALSUPPORT_DATA_PATH LALSUPPORT_OCTAVE_PATH LALSUPPORT_PYTHON_PATH
export LAL_LIBS LAL_CFLAGS LAL_DATA_PATH LAL_OCTAVE_PATH LAL_PYTHON_PATH LAL_DOCDIR
export LALSUPPORT_LIBS LALSUPPORT_CFLAGS LALSUPPORT_DATA_PATH LALSUPPORT_OCTAVE_PATH LALSUPPORT_PYTHON_PATH LALSUPPORT_DOCDIR
# configure optional packages
lalsuite_config_subdir([lalframe])
......
doxygen/.gitignore deleted 100644 → 0
View file @ 8f035ab4
*.aux
*.la
*.lo
*.loT
*.log
*.o
*.pc
*.tag
.adoc
.deps
.dvi-dep
.libs
Makefile
Makefile.in
aclocal.m4
autom4te.cache/
config.log
config.lt
config.status
configure
doxy-html-config.cfg
doxy-html-eqns.log
doxy-html-warn.log
doxy-pdf-config.cfg
doxy-pdf-make.log
doxy-pdf-warn.log
doxygen_*.tmp
figures/
html/
lalsuite-*.tar.gz
latex/
refman.pdf
doxygen/00boot deleted 100755 → 0
View file @ 8f035ab4
#!/bin/sh
## function to print error message and exit
fail () {
echo "!!! $0: $1" >&2
exit 1
}
## check script is being run from top-level source directory
test "$0" = "./00boot" || fail "must be run from top-level source directory"
## remove M4 cache files
rm -rf autom4te.cache/
rm -f aclocal.m4
# FIXME: autoreconf from Ubuntu 9.10 (and probably also from recent
# Debian versions) automatically run libtoolize with the --copy option
# therefore over writing the supplied libtool scripts with system
# version. This can lead to unexpected build failures therefore to work
# round this "feature" we set the LIBTOOLIZE enviroment variable to
# point to the the true executable which bypasses the running of
# libtoolize, this will not effect the vast majority of users and those
# it will effect will know how to run libtoolize, if required.
## run autoreconf
AUTORECONF=${AUTORECONF:-"autoreconf"}
echo "00boot: running ${AUTORECONF}"
LIBTOOLIZE=true ${AUTORECONF} || fail "${AUTORECONF} failed"
echo "
==================================================
00boot has been run successfully.
Now run './configure' with appropriate options
to configure LALSuite Doxygen.
==================================================
"
doxygen/Makefile.am deleted 100644 → 0
View file @ 8f035ab4
DOXY_HTML_FILES = \
doxy-html-config.cfg \
doxy-html-mathjax.js \
doxy-html-layout.xml
DOXY_PDF_FILES = \
doxy-pdf-config.cfg \
doxy-pdf-extra.sty \
doxy-pdf-layout.xml
EXTRA_DIST = \
$(DOXY_HTML_FILES) \
$(DOXY_PDF_FILES)
SUBDIRS = \
src
.PHONY: html pdf
override lalsuite_top_srcdir = $(abs_srcdir)/..
DOXYINPUT = \
lal \
lalburst \
laldetchar \
lalframe \
lalinference \
lalinspiral \
lalmetaio \
lalpulsar \
lalsimulation \
lalstochastic \
lalxml \
lalapps
override doxy_inputdirs = \
$(abs_srcdir)/src \
$(addprefix $(lalsuite_top_srcdir)/,$(DOXYINPUT))
override lalsuite_version = $(shell \
version="$(PACKAGE_VERSION)"; \
if test "x$(GIT)" != x; then \
hash=`cd $(lalsuite_top_srcdir) && $(GIT) rev-parse --quiet HEAD 2>/dev/null`; \
if test "x$${hash}" != x; then \
taghash=`cd $(lalsuite_top_srcdir) && $(GIT) rev-parse lalsuite-v${PACKAGE_VERSION}^{commit} 2>/dev/null`; \
unclean=`cd $(lalsuite_top_srcdir) && ( $(GIT) diff --quiet HEAD || printf %s -UNCLEAN )`; \
if test "x$${hash}" != "x$${taghash}" || test "x$${unclean}" != x; then \
version="$${version}-$${hash}$${unclean}"; \
fi; \
fi; \
fi; \
echo "$${version}" )
override TEXINPUTS = .:$(abs_srcdir):
override pool_size = 4000000
export lalsuite_top_srcdir abs_srcdir abs_builddir
export doxy_inputdirs lalsuite_version TEXINPUTS pool_size
html: $(DOXY_HTML_FILES)
@echo "===== building doxygen HTML in $(abs_builddir) ======"
@echo "DOXYINPUT=$(DOXYINPUT)"
rm -f doxy-html*.log
if doxygen $(abs_srcdir)/doxy-html-config.cfg; then \
if test -f html/_formulas.log; then \
$(LN_S) html/_formulas.log doxy-html-eqns.log; \
fi; \
fi
@echo "===== OK: done building doxygen HTML ====="
pdf: $(DOXY_PDF_FILES)
@echo "===== building doxygen PDF in $(abs_builddir) ====="
@echo "DOXYINPUT=$(DOXYINPUT)"
rm -f refman.pdf doxy-pdf*.log
if doxygen $(abs_srcdir)/doxy-pdf-config.cfg && ( cd latex && $(MAKE) ); then \
$(LN_S) latex/refman.pdf refman.pdf; \
exit 0; \
else \
$(LN_S) latex/refman.log doxy-pdf-make.log; \
exit 1; \
fi
@echo "===== OK: done building doxygen PDF ====="
clean-local:
-rm -fr html/ latex/
-rm -f refman.pdf doxy-html*.log doxy-pdf*.log
doxygen/configure.ac deleted 100644 → 0
View file @ 8f035ab4
AC_PREREQ([2.63])
AC_INIT([lalsuite-doxygen],[6.28.1],[lal-discuss@ligo.org])
AC_CONFIG_SRCDIR([configure.ac])
AC_CONFIG_AUX_DIR([gnuscripts])
AC_CONFIG_MACRO_DIR([gnuscripts])
AC_CONFIG_FILES([
Makefile \
src/Makefile
])
AM_INIT_AUTOMAKE([1.11 foreign color-tests parallel-tests])
AC_PATH_PROG(GIT, [git], [])
AC_PROG_LN_S
AC_SUBST([ac_configure_args])
AC_OUTPUT
doxygen/doxy-pdf-config.cfg deleted 100644 → 0
View file @ 8f035ab4
This diff is collapsed.
doxygen/doxy-pdf-extra.sty deleted 100644 → 0
View file @ 8f035ab4
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{doxy-pdf-extra}
\RequirePackage{amsmath}
\RequirePackage{amssymb}
\RequirePackage{wrapfig}
% Create a new DoxyImage environment, replacing the definition in the Doxygen style file. This
% environment uses the macros \doxyextrafigbegin and \doxyextrafigend to setup the figure environment.
% The definitions of \doxyextrafig{begin,end} are set as appropriate by the macro \doxyextrafig. They
% are undefined after use, so that an error is generated if a \doxyextrafig is not included before
% every DoxyImage environment.
\renewenvironment{DoxyImage}{%
\doxyextrafigbegin%
}{%
\doxyextrafigend%
\let\doxyextrafigbegin\undefined%
\let\doxyextrafigend\undefined%
}
\let\doxyextrafigbegin\undefined
\let\doxyextrafigend\undefined
% This macro sets up the new DoxyImage environment. It takes as arguments the figure label (#1) and
% its width (#2). If width is less than 0.5, it creates a right-aligned wrapped figure, otherwise it
% creates a standard floating figure. It is called by the Doxygen \figure alias.
\newdimen\doxyextrafigwidth
\def\doxyextrafig#1#2{%
\doxyextrafigwidth=#2\textwidth%
\ifdim\doxyextrafigwidth < 0.5\textwidth%
\def\doxyextrafigbegin{\wrapfigure{r}{\doxyextrafigwidth}\center}%
\def\doxyextrafigend{\label{#1}\endcenter\endwrapfigure}%
\else%
\def\doxyextrafigbegin{\figure\center}%
\def\doxyextrafigend{\label{#1}\endcenter\endfigure}%
\fi%
}
doxygen/doxy-pdf-layout.xml deleted 100644 → 0
View file @ 8f035ab4
<doxygenlayout version="1.0">
<!-- Generated by doxygen 1.8.5 -->
<!-- Navigation index tabs for HTML output -->
<navindex>
<tab type="mainpage" visible="yes" title=""/>
<tab type="pages" visible="yes" title="" intro=""/>
<tab type="modules" visible="yes" title="" intro=""/>
<tab type="namespaces" visible="yes" title="">
<tab type="namespacelist" visible="yes" title="" intro=""/>
<tab type="namespacemembers" visible="yes" title="" intro=""/>
</tab>
<tab type="classes" visible="yes" title="">
<tab type="classlist" visible="yes" title="" intro=""/>
<tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
<tab type="hierarchy" visible="yes" title="" intro=""/>
<tab type="classmembers" visible="yes" title="" intro=""/>
</tab>
<tab type="files" visible="yes" title="">
<tab type="filelist" visible="yes" title="" intro=""/>
<tab type="globals" visible="yes" title="" intro=""/>
</tab>
<tab type="examples" visible="yes" title="" intro=""/>
</navindex>
<!-- Layout definition for a class page -->
<class>
<briefdescription visible="no"/>
<detaileddescription title=""/>
<includes visible="$SHOW_INCLUDE_FILES"/>
<inheritancegraph visible="$CLASS_GRAPH"/>
<collaborationgraph visible="$COLLABORATION_GRAPH"/>
<allmemberslink visible="yes"/>
<memberdecl>
<nestedclasses visible="yes" title=""/>
<publictypes title=""/>
<publicslots title=""/>
<signals title=""/>
<publicmethods title=""/>
<publicstaticmethods title=""/>
<publicattributes title=""/>
<publicstaticattributes title=""/>
<protectedtypes title=""/>
<protectedslots title=""/>
<protectedmethods title=""/>
<protectedstaticmethods title=""/>
<protectedattributes title=""/>
<protectedstaticattributes title=""/>
<packagetypes title=""/>
<packagemethods title=""/>
<packagestaticmethods title=""/>
<packageattributes title=""/>
<packagestaticattributes title=""/>
<properties title=""/>
<events title=""/>
<privatetypes title=""/>
<privateslots title=""/>