There will be maintenance performed on git.ligo.org, chat.ligo.org, containers.lig.org, and docs.ligo.org starting at 9am PDT on Tuesday 18th August 2020. There will be an extremely small period of downtime at the start of the maintenance window as various services are restarted. Please address any comments, questions, or concerns to computing-help@igwn.org.

Commit f7eb9a04 authored by Karl Wette's avatar Karl Wette

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

Too many changes to show.

To preserve performance only 1000 of 1000+ files are displayed.

......@@ -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
%!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