Skip to content

Commit 88ca006

Browse files
sethrjsethrj
authored
Add PDF documentation for technical memo output (#28)
1 parent d76cbd9 commit 88ca006

15 files changed

+640
-119
lines changed

‎CMakeLists.txt

+4
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,10 @@ if(FLIBCPP_BUILD_TESTS OR FLIBCPP_BUILD_EXAMPLES)
6868
include(CTest)
6969
endif()
7070

71+
if(FLIBCPP_BUILD_DOCS)
72+
find_package(Sphinx REQUIRED)
73+
endif()
74+
7175
#---------------------------------------------------------------------------#
7276
# LIBRARY
7377
#---------------------------------------------------------------------------#

‎LICENSE

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
MIT License
22

3-
Copyright (c) 2019--2020 Oak Ridge National Laboratory, UT--Battelle, LLC.
3+
Copyright (c) 2019--2021 Oak Ridge National Laboratory, UT--Battelle, LLC.
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal

‎doc/CMakeLists.txt

+31-5
Original file line numberDiff line numberDiff line change
@@ -5,20 +5,46 @@
55
# Distributed under an MIT open source license: see LICENSE for details.
66
#---------------------------------------------------------------------------#
77

8-
find_package(Sphinx REQUIRED)
9-
8+
configure_file("version.json.in" "version.json" @ONLY)
109
add_custom_target(doc ALL)
1110
add_custom_command(TARGET doc
12-
COMMAND "${SPHINX_EXECUTABLE}" -q
11+
COMMAND "${CMAKE_COMMAND}" -E env
12+
"CMAKE_CURRENT_BINARY_DIR=${CMAKE_CURRENT_BINARY_DIR}"
13+
"${SPHINX_EXECUTABLE}" -q
1314
-d "${CMAKE_CURRENT_BINARY_DIR}/doctrees"
1415
-b html
1516
"${CMAKE_CURRENT_SOURCE_DIR}"
1617
"${CMAKE_CURRENT_BINARY_DIR}/html"
1718
WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}"
1819
COMMENT "Building HTML documentation with Sphinx"
1920
BYPRODUCTS "${CMAKE_CURRENT_BINARY_DIR}/html/index.html"
20-
)
21+
)
22+
23+
# Note: latex generation creates a makefile that muts be run
24+
add_custom_target(doc_latex)
25+
add_custom_command(TARGET doc_latex
26+
COMMAND "${CMAKE_COMMAND}" -E env
27+
"CMAKE_CURRENT_BINARY_DIR=${CMAKE_CURRENT_BINARY_DIR}"
28+
"${SPHINX_EXECUTABLE}" -q
29+
-d "${CMAKE_CURRENT_BINARY_DIR}/doctrees"
30+
-b latex
31+
"${CMAKE_CURRENT_SOURCE_DIR}"
32+
"${CMAKE_CURRENT_BINARY_DIR}/latex"
33+
COMMENT "Building LaTeX documentation with Sphinx"
34+
BYPRODUCTS "${CMAKE_CURRENT_BINARY_DIR}/latex/Flibcpp.tex"
35+
)
36+
add_custom_target(doc_pdf)
37+
add_custom_command(TARGET doc_pdf
38+
COMMAND "${CMAKE_COMMAND}" -E env
39+
"LATEXOPTS="
40+
latexmk -pdf flibcpp-tm-header Flibcpp
41+
WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/latex"
42+
COMMENT "Building PDF documentation from LaTeX"
43+
BYPRODUCTS "${CMAKE_CURRENT_BINARY_DIR}/latex/Flibcpp.pdf"
44+
)
45+
add_dependencies(doc_pdf doc_latex)
2146

2247
install(DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/html/"
2348
DESTINATION "${CMAKE_INSTALL_DOCDIR}"
24-
)
49+
)
50+

‎doc/_static/flibcpp-tm-header.tex

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
\documentclass{ornltm}
2+
3+
\author{Seth R.~Johnson}
4+
\title{Flibcpp User Manual}
5+
\date{Aug.~2021}
6+
\reportnum{ORNL/TM-2021/2041}
7+
\reportdraft
8+
\division{Computational Sciences and Engineering Division}
9+
10+
\begin{document}
11+
\frontmatter
12+
\end{document}

‎doc/_static/ornltm-extract.sty

+64
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2+
% File : doc/_sphinx/latex/ornltm-extract.sty
3+
% Author: Seth R Johnson
4+
% Date : Sat Oct 13 13:04:10 2018
5+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
6+
7+
\NeedsTeXFormat{LaTeX2e}[1995/12/01]
8+
\ProvidesPackage{ornltm-extract}[2018/11/13 package ORNL Technical Memorandum
9+
commands]
10+
11+
\ProcessOptions\relax
12+
13+
\RequirePackage{emptypage} % hide footers on blank pages
14+
15+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
16+
% FRONT MATTER
17+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
18+
19+
\newif\if@mainmatter
20+
\@mainmattertrue
21+
\def\@cleariffrontmatter{\if@mainmatter\relax\else{\clearpage}\fi}
22+
\def\@cleardbliffrontmatter{\if@mainmatter\relax\else{\cleardoublepage}\fi}
23+
24+
\newcommand\frontmatter{%
25+
\@mainmatterfalse%
26+
% Reset page numbering for user-added front matter
27+
\pagenumbering{roman}%
28+
\setcounter{page}{3}%
29+
}
30+
31+
% Abstract gets a new page if it's in the front matter; otherwise it's just at
32+
% the top of the page.
33+
\renewenvironment{abstract}{%
34+
\if@mainmatter\relax\else
35+
\cleardoublepage
36+
\pagenumbering{arabic}
37+
\setcounter{page}{1}
38+
\fi
39+
\addcontentsline{toc}{section}{Abstract}
40+
\phantomsection
41+
\section*{Abstract}%
42+
}{}
43+
44+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
45+
% MAIN MATTER
46+
%
47+
% not quite the same as in ornltm.cls
48+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
49+
50+
\newcommand\mainmatter{%
51+
\cleardoublepage%
52+
\@mainmattertrue%
53+
\pagenumbering{arabic}%
54+
\setcounter{page}{1}
55+
\renewcommand{\sectionbreak}{\renewcommand\sectionbreak\cleardoublepage}
56+
}
57+
58+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
59+
60+
\endinput
61+
62+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
63+
% end of ornltm/ornltm/ornltm-style.tex
64+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

‎doc/_static/ornltm-style.sty

+190
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2+
% File : doc/_sphinx/latex/ornltm-style.sty
3+
% Author: Seth R Johnson
4+
% Date : Sat Oct 13 13:04:10 2018
5+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
6+
7+
\NeedsTeXFormat{LaTeX2e}[1995/12/01]
8+
\ProvidesPackage{ornltm-style}[2018/10/13 package ORNL Technical Memorandum style]
9+
10+
\ProcessOptions\relax
11+
12+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
13+
% GEOMETRY
14+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
15+
16+
\RequirePackage{geometry}
17+
\geometry{margin=1in,footskip=.75in}
18+
19+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
20+
% FONTS
21+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
22+
23+
% ams math must be loaded before txfonts
24+
\RequirePackage{amsmath}
25+
26+
% Use Times for math font and text font.
27+
\RequirePackage[T1]{fontenc}
28+
\RequirePackage{txfonts}
29+
30+
% Bold math must be loaded after Times font
31+
\RequirePackage{bm}
32+
33+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
34+
% COLORS
35+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
36+
37+
\RequirePackage{color} % colored fonts and boxes
38+
39+
% Add pretty link colors if hyperref is loaded
40+
\@ifpackageloaded{hyperref}{\hypersetup{
41+
colorlinks,
42+
linkcolor=[rgb]{0.01,0.05,0.1},
43+
citecolor=[rgb]{0.780,0.647,0.258},
44+
urlcolor=[rgb]{0.325,0.494,0.658}
45+
}}{}
46+
47+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
48+
% LINE SPACING
49+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
50+
51+
% Do not indent paragraphs
52+
% Note: do NOT use the parskip package: it breaks tocloft; the parfill option
53+
% also breaks \hfill!
54+
55+
\setlength\parskip{0.5\baselineskip \@plus 0.25\baselineskip \@minus 0.25\baselineskip}
56+
\setlength\parindent\z@
57+
\setlength\partopsep\z@
58+
59+
% Update spacing in lists.
60+
\def\@listI{\leftmargin\leftmargini
61+
\topsep\z@ \parsep\parskip \itemsep\z@}
62+
\let\@listi\@listI
63+
\@listi
64+
65+
\def\@listii{\leftmargin\leftmarginii
66+
\labelwidth\leftmarginii\advance\labelwidth-\labelsep
67+
\topsep\z@ \parsep\parskip \itemsep\z@}
68+
69+
\def\@listiii{\leftmargin\leftmarginiii
70+
\labelwidth\leftmarginiii\advance\labelwidth-\labelsep
71+
\topsep\z@ \parsep\parskip \itemsep\z@}
72+
73+
74+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
75+
% TABLE OF CONTENTS STYLING
76+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
77+
78+
\RequirePackage{tocloft} % table of contents styling
79+
80+
\setcounter{tocdepth}{2} % subsections
81+
82+
% Make the contents, figure, and table titles uppercase and centered
83+
\renewcommand\cfttoctitlefont{\noindent\hspace*{\fill}\bfseries\MakeUppercase}
84+
\renewcommand\cftloftitlefont{\noindent\hspace*{\fill}\bfseries\MakeUppercase}
85+
\renewcommand\cftlottitlefont{\noindent\hspace*{\fill}\bfseries\MakeUppercase}
86+
\renewcommand\cftaftertoctitle{\hspace*{\fill}}
87+
\renewcommand\cftafterloftitle{\hspace*{\fill}}
88+
\renewcommand\cftafterlottitle{\hspace*{\fill}}
89+
% Use plain font style and regular size
90+
\renewcommand\cftsecfont{}
91+
% Add a dot after section numbers
92+
\renewcommand\cftsecaftersnum{.}
93+
% Squish section lines together
94+
\setlength\cftbeforesecskip{0pt}
95+
% Add leaders to all sections and subsections in the TOC.
96+
\renewcommand\cftsecleader{\cftdotfill{\cftdotsep}}
97+
98+
%%% EXTENSIONS FOR SPHINX MANUAL %%%
99+
100+
\if@cfthaspart
101+
\setlength\cftbeforepartskip{.25\baselineskip}
102+
\fi
103+
104+
\if@cfthaschapter
105+
\setlength\cftbeforechapskip{.5\baselineskip}
106+
\fi
107+
108+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
109+
% TITLE STYLES
110+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
111+
112+
\RequirePackage{titlesec} % title modification: use text size
113+
114+
% Show five levels of depth in title labels
115+
\setcounter{secnumdepth}{5}
116+
117+
% Break at the beginning of sections.
118+
\titleclass{\section}{top}
119+
\newcommand{\sectionbreak}{\clearpage}
120+
121+
% You may need to use the \texorpdfstring when using hyperref and
122+
% unusual titles.
123+
\titleformat{\section}{\centering\bf}{\thesection.}{1ex}{\MakeUppercase}[]
124+
\titleformat{\subsection}{\bf}{\thesubsection}{1ex}{\MakeUppercase}[]
125+
\titleformat{\subsubsection}{\bf}{\thesubsubsection}{1ex}{\MakeUppercase}[]
126+
\titleformat{\paragraph}{\bf}{\theparagraph}{1ex}{}[]
127+
\titleformat{\subparagraph}{\bf\itshape}{\relax}{0pt}{}[]
128+
129+
% Update spacing to account for our custom parskip.
130+
\titlespacing{\section}{\z@}{\parskip}{\z@}
131+
\titlespacing{\subsection}{\z@}{\parskip}{\z@}
132+
\titlespacing{\subsubsection}{\z@}{0.5\parskip}{\z@}
133+
\titlespacing{\paragraph}{\z@}{0.5\parskip}{\z@}
134+
\titlespacing{\subparagraph}{\z@}{0.5\parskip}{\z@}
135+
136+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
137+
% APPENDIX PAGE NUMBERING
138+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
139+
140+
% Define a ``section'' command for the appendix
141+
\newcommand\@appendixsection[1]{%
142+
\cleardoublepage
143+
% Call the ``section'' command, which will put the title on its own page
144+
\thispagestyle{empty}
145+
\@oldappendixsection{#1}
146+
% Increment page counter
147+
\stepcounter{page}%
148+
% Add a blank page after the title
149+
\cleardoublepage
150+
% Insert the appendix name at the top, with no number
151+
{\hfill\bf\appendixname~\thesection.\hspace{.5em}\MakeUppercase{#1}%
152+
\hfill\null\par}
153+
}
154+
155+
\renewcommand\appendixname{APPENDIX}
156+
157+
% Change format for appendices: 'appendix' in title, title takes entire page,
158+
% is not numbered, followed by a blank unnumbered page.
159+
\renewcommand\appendix{%
160+
\cleardoublepage
161+
% Reset page style
162+
\pagenumbering{arabic}%
163+
\renewcommand\thepage{\thesection--\arabic{page}}%
164+
% Reset section numbering
165+
\gdef\thesection{\@Alph\c@section}%
166+
% Reset section formatting
167+
\setcounter{section}{0}%
168+
% Change equation numbering
169+
\gdef\theequation{\@Alph\c@section.\arabic{equation}}%
170+
% Reset page and equation numbers at the beginning of every section
171+
\@addtoreset{equation}{section}%
172+
\@addtoreset{page}{section}%
173+
% Change the title format so that the ``header'' is a standalone title page.
174+
% This allows section and page numbering to be correct, and we can use the
175+
% macros it defines to insert a ``regular'' appendix label afterward.
176+
\titleformat{\section}[block]{\null\vfill\bf\filcenter}%
177+
{\appendixname~\thesection.}{0.5em}{\bf\large\MakeUppercase}[\vfill\null]
178+
% Save the command we just defined; we'll use it in a command we defined above
179+
% outside the ``appendix'' macro.
180+
\let\@oldappendixsection\section
181+
\let\section\@appendixsection
182+
}
183+
184+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
185+
186+
\endinput
187+
188+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
189+
% end of ornltm/ornltm/ornltm-style.tex
190+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

‎doc/_static/references.bib

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
@article{beazley_automated_2003,
2+
title = {Automated scientific software scripting with {SWIG}},
3+
volume = {19},
4+
issn = {0167739X},
5+
url = {http://linkinghub.elsevier.com/retrieve/pii/S0167739X02001711},
6+
doi = {10.1016/S0167-739X(02)00171-1},
7+
abstract = {Scripting languages such as Python and Tcl are a powerful tool for the construction of flexible scientific software because they provide scientists with an interpreted problem solving environment and they provide a modular framework for controlling software components written in C, C++, and Fortran. However, a common problem faced by the developers of a scripted scientific application is that of integrating compiled code with an interpreter. To solve this problem, an extensible compiler, simplified wrapper and interface generator (SWIG), has been developed to automate the task of integrating compiled code with scripting language interpreters. SWIG requires no modifications to existing code and uses existing source to create bindings for nine different target languages including Python, Perl, Tcl, Ruby, Guile, and Java. By automating language integration, SWIG enables scientists to use scripting languages at all stages of software development and allows existing software to be more easily integrated into a scripting environment. Although SWIG has been in use for more than 6 years, little has been published on its design and the underlying mechanisms that make it work. Therefore, the primary goal of this paper is to cover these topics.},
8+
language = {en},
9+
number = {5},
10+
urldate = {2018-09-06},
11+
journal = {Future Generation Computer Systems},
12+
author = {Beazley, D.M.},
13+
month = jul,
14+
year = {2003},
15+
pages = {599--609},
16+
file = {Beazley - 2003 - Automated scientific software scripting with SWIG.pdf:/Users/s3j/Zotero/storage/LKCUYK6D/Beazley - 2003 - Automated scientific software scripting with SWIG.pdf:application/pdf}
17+
}
18+
19+
@article{mcinnes_how_2021,
20+
title = {How community software ecosystems can unlock the potential of exascale computing},
21+
volume = {1},
22+
issn = {2662-8457},
23+
url = {http://www.nature.com/articles/s43588-021-00033-y},
24+
doi = {10.1038/s43588-021-00033-y},
25+
language = {en},
26+
number = {2},
27+
urldate = {2021-05-22},
28+
journal = {Nature Computational Science},
29+
author = {McInnes, Lois Curfman and Heroux, Michael A. and Draeger, Erik W. and Siegel, Andrew and Coghlan, Susan and Antypas, Katie},
30+
month = feb,
31+
year = {2021},
32+
pages = {92--94},
33+
file = {McInnes et al. - 2021 - How community software ecosystems can unlock the p.pdf:/Users/s3j/Zotero/storage/T5G46MCK/McInnes et al. - 2021 - How community software ecosystems can unlock the p.pdf:application/pdf}
34+
}
35+
36+
@article{johnson_automated_2020,
37+
title = {Automated {Fortran}-{C}++ {Bindings} for {Large}-{Scale} {Scientific} {Applications}},
38+
volume = {22},
39+
issn = {1521-9615, 1558-366X},
40+
url = {https://ieeexplore.ieee.org/document/8745480/},
41+
doi = {10.1109/MCSE.2019.2924204},
42+
abstract = {Although many active scientific codes use modern Fortran, most contemporary scientific software libraries are implemented in C and C++. Providing their numerical, algorithmic, or data management features to Fortran codes requires writing and maintaining substantial amounts of glue code. This article introduces a tool that automatically generates native Fortran 2003 interfaces to C and C++ libraries. The tool supports C++ features that have no direct Fortran analog, such as templated functions and exceptions. A set of simple examples demonstrate the utility and scope of the tool, and timing measurements with a mock numerical library illustrate the minimal performance impact of the generated wrapper code.},
43+
language = {en},
44+
number = {5},
45+
urldate = {2019-08-20},
46+
journal = {Computing in Science \& Engineering},
47+
author = {Johnson, Seth R. and Prokopenko, Andrey and Evans, Katherine J.},
48+
month = oct,
49+
year = {2020},
50+
pages = {84--94},
51+
file = {Johnson et al. - 2020 - Automated Fortran-C++ Bindings for Large-Scale Sci.pdf:/Users/s3j/Zotero/storage/IDWGIGJQ/Johnson et al. - 2020 - Automated Fortran-C++ Bindings for Large-Scale Sci.pdf:application/pdf}
52+
}

0 commit comments

Comments
 (0)