Skip to content

GitLab

L
lalsuite

Maintenance will be performed on git.ligo.org, chat.ligo.org, containers.ligo.org, and docs.ligo.org on Tuesday 22nd September 2020 starting at approximately 9am MST.It is expected to take around 15 minutes and there will be a short period of downtime towards the end of the maintenance window. Please address any comments, questions, or concerns to computing-help@igwn.org.

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

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 14069 additions and 68112 deletions

Too many changes to show.
Plain diff Email patch

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

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