Add PDF documentation for technical memo output (#28)

CMakeLists.txt

@@ -68,6 +68,10 @@ if(FLIBCPP_BUILD_TESTS OR FLIBCPP_BUILD_EXAMPLES)
   include(CTest)
 endif()
 
+if(FLIBCPP_BUILD_DOCS)
+  find_package(Sphinx REQUIRED)
+endif()
+
 #---------------------------------------------------------------------------#
 # LIBRARY
 #---------------------------------------------------------------------------#

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019--2020 Oak Ridge National Laboratory, UT--Battelle, LLC.
+Copyright (c) 2019--2021 Oak Ridge National Laboratory, UT--Battelle, LLC.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

doc/CMakeLists.txt

@@ -5,20 +5,46 @@
 # Distributed under an MIT open source license: see LICENSE for details.
 #---------------------------------------------------------------------------#
 
-find_package(Sphinx REQUIRED)
-
+configure_file("version.json.in" "version.json" @ONLY)
 add_custom_target(doc ALL)
 add_custom_command(TARGET doc
-  COMMAND "${SPHINX_EXECUTABLE}" -q
+  COMMAND "${CMAKE_COMMAND}" -E env
+  "CMAKE_CURRENT_BINARY_DIR=${CMAKE_CURRENT_BINARY_DIR}"
+  "${SPHINX_EXECUTABLE}" -q
     -d "${CMAKE_CURRENT_BINARY_DIR}/doctrees"
     -b html
     "${CMAKE_CURRENT_SOURCE_DIR}"
     "${CMAKE_CURRENT_BINARY_DIR}/html"
   WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}"
   COMMENT "Building HTML documentation with Sphinx"
   BYPRODUCTS "${CMAKE_CURRENT_BINARY_DIR}/html/index.html"
-  )
+)
+
+# Note: latex generation creates a makefile that muts be run
+add_custom_target(doc_latex)
+add_custom_command(TARGET doc_latex
+  COMMAND "${CMAKE_COMMAND}" -E env
+  "CMAKE_CURRENT_BINARY_DIR=${CMAKE_CURRENT_BINARY_DIR}"
+  "${SPHINX_EXECUTABLE}" -q
+    -d "${CMAKE_CURRENT_BINARY_DIR}/doctrees"
+    -b latex
+    "${CMAKE_CURRENT_SOURCE_DIR}"
+    "${CMAKE_CURRENT_BINARY_DIR}/latex"
+  COMMENT "Building LaTeX documentation with Sphinx"
+  BYPRODUCTS "${CMAKE_CURRENT_BINARY_DIR}/latex/Flibcpp.tex"
+)
+add_custom_target(doc_pdf)
+add_custom_command(TARGET doc_pdf
+  COMMAND "${CMAKE_COMMAND}" -E env
+  "LATEXOPTS="
+  latexmk -pdf flibcpp-tm-header Flibcpp
+  WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/latex"
+  COMMENT "Building PDF documentation from LaTeX"
+  BYPRODUCTS "${CMAKE_CURRENT_BINARY_DIR}/latex/Flibcpp.pdf"
+)
+add_dependencies(doc_pdf doc_latex)
 
 install(DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/html/"
   DESTINATION "${CMAKE_INSTALL_DOCDIR}"
-  )
+)
+

doc/_static/flibcpp-tm-header.tex

@@ -0,0 +1,12 @@
+\documentclass{ornltm}
+
+\author{Seth R.~Johnson}
+\title{Flibcpp User Manual}
+\date{Aug.~2021}
+\reportnum{ORNL/TM-2021/2041}
+\reportdraft
+\division{Computational Sciences and Engineering Division}
+
+\begin{document}
+\frontmatter
+\end{document}

doc/_static/ornltm-extract.sty

@@ -0,0 +1,64 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% File  : doc/_sphinx/latex/ornltm-extract.sty
+% Author: Seth R Johnson
+% Date  : Sat Oct 13 13:04:10 2018
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\NeedsTeXFormat{LaTeX2e}[1995/12/01]
+\ProvidesPackage{ornltm-extract}[2018/11/13 package ORNL Technical Memorandum
+commands]
+
+\ProcessOptions\relax
+
+\RequirePackage{emptypage} % hide footers on blank pages
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% FRONT MATTER
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\newif\if@mainmatter
+\@mainmattertrue
+\def\@cleariffrontmatter{\if@mainmatter\relax\else{\clearpage}\fi}
+\def\@cleardbliffrontmatter{\if@mainmatter\relax\else{\cleardoublepage}\fi}
+
+\newcommand\frontmatter{%
+  \@mainmatterfalse%
+  % Reset page numbering for user-added front matter
+  \pagenumbering{roman}%
+  \setcounter{page}{3}%
+}
+
+% Abstract gets a new page if it's in the front matter; otherwise it's just at
+% the top of the page.
+\renewenvironment{abstract}{%
+\if@mainmatter\relax\else
+  \cleardoublepage
+	\pagenumbering{arabic}
+	\setcounter{page}{1}
+\fi
+	\addcontentsline{toc}{section}{Abstract}
+	\phantomsection
+  \section*{Abstract}%
+}{}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% MAIN MATTER
+%
+% not quite the same as in ornltm.cls
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\newcommand\mainmatter{%
+  \cleardoublepage%
+  \@mainmattertrue%
+  \pagenumbering{arabic}%
+	\setcounter{page}{1}
+  \renewcommand{\sectionbreak}{\renewcommand\sectionbreak\cleardoublepage}
+}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\endinput
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% end of ornltm/ornltm/ornltm-style.tex
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

doc/_static/ornltm-style.sty

@@ -0,0 +1,190 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% File  : doc/_sphinx/latex/ornltm-style.sty
+% Author: Seth R Johnson
+% Date  : Sat Oct 13 13:04:10 2018
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\NeedsTeXFormat{LaTeX2e}[1995/12/01]
+\ProvidesPackage{ornltm-style}[2018/10/13 package ORNL Technical Memorandum style]
+
+\ProcessOptions\relax
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% GEOMETRY
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\RequirePackage{geometry}
+\geometry{margin=1in,footskip=.75in}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% FONTS
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+% ams math must be loaded before txfonts
+\RequirePackage{amsmath}
+
+% Use Times for math font and text font.
+\RequirePackage[T1]{fontenc}
+\RequirePackage{txfonts}
+
+% Bold math must be loaded after Times font
+\RequirePackage{bm}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% COLORS
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\RequirePackage{color} % colored fonts and boxes
+
+% Add pretty link colors if hyperref is loaded
+\@ifpackageloaded{hyperref}{\hypersetup{
+	colorlinks,
+  linkcolor=[rgb]{0.01,0.05,0.1},
+	citecolor=[rgb]{0.780,0.647,0.258},
+	urlcolor=[rgb]{0.325,0.494,0.658}
+}}{}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% LINE SPACING
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+% Do not indent paragraphs
+% Note: do NOT use the parskip package: it breaks tocloft; the parfill option
+% also breaks \hfill!
+
+\setlength\parskip{0.5\baselineskip \@plus 0.25\baselineskip \@minus 0.25\baselineskip}
+\setlength\parindent\z@
+\setlength\partopsep\z@
+
+% Update spacing in lists.
+\def\@listI{\leftmargin\leftmargini
+   \topsep\z@ \parsep\parskip \itemsep\z@}
+\let\@listi\@listI
+\@listi
+
+\def\@listii{\leftmargin\leftmarginii
+   \labelwidth\leftmarginii\advance\labelwidth-\labelsep
+   \topsep\z@ \parsep\parskip \itemsep\z@}
+
+\def\@listiii{\leftmargin\leftmarginiii
+    \labelwidth\leftmarginiii\advance\labelwidth-\labelsep
+    \topsep\z@ \parsep\parskip \itemsep\z@}
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% TABLE OF CONTENTS STYLING
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\RequirePackage{tocloft} % table of contents styling
+
+\setcounter{tocdepth}{2} % subsections
+
+% Make the contents, figure, and table titles uppercase and centered
+\renewcommand\cfttoctitlefont{\noindent\hspace*{\fill}\bfseries\MakeUppercase}
+\renewcommand\cftloftitlefont{\noindent\hspace*{\fill}\bfseries\MakeUppercase}
+\renewcommand\cftlottitlefont{\noindent\hspace*{\fill}\bfseries\MakeUppercase}
+\renewcommand\cftaftertoctitle{\hspace*{\fill}}
+\renewcommand\cftafterloftitle{\hspace*{\fill}}
+\renewcommand\cftafterlottitle{\hspace*{\fill}}
+% Use plain font style and regular size
+\renewcommand\cftsecfont{}
+% Add a dot after section numbers
+\renewcommand\cftsecaftersnum{.}
+% Squish section lines together
+\setlength\cftbeforesecskip{0pt}
+% Add leaders to all sections and subsections in the TOC.
+\renewcommand\cftsecleader{\cftdotfill{\cftdotsep}}
+
+%%% EXTENSIONS FOR SPHINX MANUAL %%%
+
+\if@cfthaspart
+\setlength\cftbeforepartskip{.25\baselineskip}
+\fi
+
+\if@cfthaschapter
+\setlength\cftbeforechapskip{.5\baselineskip}
+\fi
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% TITLE STYLES 
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\RequirePackage{titlesec} % title modification: use text size
+
+% Show five levels of depth in title labels
+\setcounter{secnumdepth}{5} 
+
+% Break at the beginning of sections.
+\titleclass{\section}{top}
+\newcommand{\sectionbreak}{\clearpage}
+
+% You may need to use the \texorpdfstring when using hyperref and
+% unusual titles.
+\titleformat{\section}{\centering\bf}{\thesection.}{1ex}{\MakeUppercase}[]
+\titleformat{\subsection}{\bf}{\thesubsection}{1ex}{\MakeUppercase}[]
+\titleformat{\subsubsection}{\bf}{\thesubsubsection}{1ex}{\MakeUppercase}[]
+\titleformat{\paragraph}{\bf}{\theparagraph}{1ex}{}[]
+\titleformat{\subparagraph}{\bf\itshape}{\relax}{0pt}{}[]
+
+% Update spacing to account for our custom parskip.
+\titlespacing{\section}{\z@}{\parskip}{\z@}
+\titlespacing{\subsection}{\z@}{\parskip}{\z@}
+\titlespacing{\subsubsection}{\z@}{0.5\parskip}{\z@}
+\titlespacing{\paragraph}{\z@}{0.5\parskip}{\z@}
+\titlespacing{\subparagraph}{\z@}{0.5\parskip}{\z@}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% APPENDIX PAGE NUMBERING
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+% Define a ``section'' command for the appendix
+\newcommand\@appendixsection[1]{%
+  \cleardoublepage
+  % Call the ``section'' command, which will put the title on its own page
+  \thispagestyle{empty}
+  \@oldappendixsection{#1}
+  % Increment page counter
+  \stepcounter{page}%
+  % Add a blank page after the title
+  \cleardoublepage
+  % Insert the appendix name at the top, with no number
+  {\hfill\bf\appendixname~\thesection.\hspace{.5em}\MakeUppercase{#1}%
+   \hfill\null\par}
+}
+
+\renewcommand\appendixname{APPENDIX}
+
+% Change format for appendices: 'appendix' in title, title takes entire page,
+% is not numbered, followed by a blank unnumbered page.
+\renewcommand\appendix{%
+  \cleardoublepage
+  % Reset page style
+  \pagenumbering{arabic}%
+  \renewcommand\thepage{\thesection--\arabic{page}}%
+  % Reset section numbering
+  \gdef\thesection{\@Alph\c@section}%
+  % Reset section formatting
+  \setcounter{section}{0}%
+  % Change equation numbering
+  \gdef\theequation{\@Alph\c@section.\arabic{equation}}%
+  % Reset page and equation numbers at the beginning of every section
+  \@addtoreset{equation}{section}%
+  \@addtoreset{page}{section}%
+  % Change the title format so that the ``header'' is a standalone title page.
+  % This allows section and page numbering to be correct, and we can use the
+  % macros it defines to insert a ``regular'' appendix label afterward.
+	\titleformat{\section}[block]{\null\vfill\bf\filcenter}%
+    {\appendixname~\thesection.}{0.5em}{\bf\large\MakeUppercase}[\vfill\null]
+  % Save the command we just defined; we'll use it in a command we defined above
+  % outside the ``appendix'' macro.
+  \let\@oldappendixsection\section
+  \let\section\@appendixsection
+}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\endinput
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% end of ornltm/ornltm/ornltm-style.tex
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

doc/_static/references.bib

@@ -0,0 +1,52 @@
+@article{beazley_automated_2003,
+	title = {Automated scientific software scripting with {SWIG}},
+	volume = {19},
+	issn = {0167739X},
+	url = {http://linkinghub.elsevier.com/retrieve/pii/S0167739X02001711},
+	doi = {10.1016/S0167-739X(02)00171-1},
+	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.},
+	language = {en},
+	number = {5},
+	urldate = {2018-09-06},
+	journal = {Future Generation Computer Systems},
+	author = {Beazley, D.M.},
+	month = jul,
+	year = {2003},
+	pages = {599--609},
+	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}
+}
+
+@article{mcinnes_how_2021,
+	title = {How community software ecosystems can unlock the potential of exascale computing},
+	volume = {1},
+	issn = {2662-8457},
+	url = {http://www.nature.com/articles/s43588-021-00033-y},
+	doi = {10.1038/s43588-021-00033-y},
+	language = {en},
+	number = {2},
+	urldate = {2021-05-22},
+	journal = {Nature Computational Science},
+	author = {McInnes, Lois Curfman and Heroux, Michael A. and Draeger, Erik W. and Siegel, Andrew and Coghlan, Susan and Antypas, Katie},
+	month = feb,
+	year = {2021},
+	pages = {92--94},
+	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}
+}
+
+@article{johnson_automated_2020,
+	title = {Automated {Fortran}-{C}++ {Bindings} for {Large}-{Scale} {Scientific} {Applications}},
+	volume = {22},
+	issn = {1521-9615, 1558-366X},
+	url = {https://ieeexplore.ieee.org/document/8745480/},
+	doi = {10.1109/MCSE.2019.2924204},
+	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.},
+	language = {en},
+	number = {5},
+	urldate = {2019-08-20},
+	journal = {Computing in Science \& Engineering},
+	author = {Johnson, Seth R. and Prokopenko, Andrey and Evans, Katherine J.},
+	month = oct,
+	year = {2020},
+	pages = {84--94},
+	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}
+}