Improve pdf/latex doc generation

- Find latexmk instead of assuming it's there
- Download ornltm at build time and set in TEXINPUTS
- Add interdependencies between pdf doc stages
- Generate and append footer

Author: sethrj

CMakeLists.txt

@@ -66,6 +66,10 @@ endif()
 
 if(FLIBCPP_BUILD_DOCS)
   find_package(Sphinx REQUIRED)
+  include(ExternalProject) # for pdf header
+  set(FLIBCPP_PYTHONPATH "$ENV{PYTHONPATH}" CACHE STRING
+    "Python path used for generating documentation"
+  )
 endif()
 
 #---------------------------------------------------------------------------#

doc/CMakeLists.txt

@@ -6,45 +6,90 @@
 #---------------------------------------------------------------------------#
 
 configure_file("version.json.in" "version.json" @ONLY)
-add_custom_target(doc ALL)
-add_custom_command(TARGET doc
-  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"
+
+function(flibcpp_build_sphinx type output)
+  add_custom_command(OUTPUT "${output}"
+    VERBATIM COMMAND
+      "${CMAKE_COMMAND}" -E env
+        "PYTHONPATH=${FLIBCPP_PYTHONPATH}"
+        "CMAKE_CURRENT_BINARY_DIR=${CMAKE_CURRENT_BINARY_DIR}"
+      "${SPHINX_EXECUTABLE}" -q
+        -d "${CMAKE_CURRENT_BINARY_DIR}/doctrees"
+        -b ${type}
+        "${CMAKE_CURRENT_SOURCE_DIR}"
+        "${CMAKE_CURRENT_BINARY_DIR}/${type}"
+    COMMENT "Building ${type} documentation with Sphinx"
+    DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/conf.py"
+    WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}"
+    ${ARGN}
+  )
+endfunction()
+
+set(_doc_html "${CMAKE_CURRENT_BINARY_DIR}/html/index.html")
+flibcpp_build_sphinx(html "${_doc_html}")
+add_custom_target(doc ALL DEPENDS "${_doc_html}")
+
+install(DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/html/"
+  DESTINATION "${CMAKE_INSTALL_DOCDIR}"
 )
 
-# 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"
+# Note: latex generation creates a makefile that must be run
+set(_doc_tex "${CMAKE_CURRENT_BINARY_DIR}/latex/Flibcpp.tex")
+flibcpp_build_sphinx(latex "${_doc_tex}")
+
+find_program(LATEXMK_EXECUTABLE latexmk)
+if(NOT LATEXMK_EXECUTABLE)
+  # Local variable to give helpful error at runtime?
+  set(LATEXMK_EXECUTABLE latexmk)
+endif()
+
+# Download ornltm class
+set(_ornltm_base "${CMAKE_CURRENT_BINARY_DIR}/latex/ornltm")
+ExternalProject_Add(ornltm
+  GIT_REPOSITORY https://code.ornl.gov/s3j/ornltm.git
+  GIT_TAG 2ad59291117b487666d15d10a105de0d680e72a6
+  CONFIGURE_COMMAND ""
+  BUILD_COMMAND ""
+  INSTALL_COMMAND ""
+  SOURCE_DIR "${_ornltm_base}"
 )
-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"
+
+set(_texenv "LATEXOPTS=" "TEXINPUTS=${_ornltm_base}/ornltm:")
+function(flibcpp_build_latex input output)
+  add_custom_command(OUTPUT "${output}"
+    VERBATIM COMMAND
+    "${CMAKE_COMMAND}" -E env ${_texenv}
+      "${LATEXMK_EXECUTABLE}" -pdf "${input}"
+    WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/latex"
+    ${ARGN}
+  )
+endfunction()
+
+# Generate header
+set(_header_pdf "${CMAKE_CURRENT_BINARY_DIR}/latex/flibcpp-tm-header.pdf")
+flibcpp_build_latex(
+  "${CMAKE_CURRENT_SOURCE_DIR}/_static/flibcpp-tm-header.tex"
+  "${_header_pdf}"
+  COMMENT "Building tech memo header"
+  DEPENDS ornltm
 )
-add_dependencies(doc_pdf doc_latex)
 
-install(DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/html/"
-  DESTINATION "${CMAKE_INSTALL_DOCDIR}"
+# Generate header
+set(_footer_pdf "${CMAKE_CURRENT_BINARY_DIR}/latex/flibcpp-tm-footer.pdf")
+flibcpp_build_latex(
+  "${CMAKE_CURRENT_SOURCE_DIR}/_static/flibcpp-tm-footer.tex"
+  "${_footer_pdf}"
+  COMMENT "Building tech memo footer"
+  DEPENDS ornltm
+)
+
+# Generate PDF
+set(_doc_pdf "${CMAKE_CURRENT_BINARY_DIR}/latex/Flibcpp.pdf")
+flibcpp_build_latex(
+  Flibcpp
+  "${_doc_pdf}"
+  COMMENT "Building PDF documentation from LaTeX"
+  DEPENDS "${_doc_tex}" "${_header_pdf}" "${_footer_pdf}" ornltm
 )
 
+add_custom_target(doc_pdf DEPENDS "${_doc_pdf}")

doc/_static/flibcpp-tm-footer.tex

@@ -0,0 +1,7 @@
+\documentclass{ornltm}
+
+\author{Seth R.~Johnson}
+
+\begin{document}
+\backmatter
+\end{document}

doc/_static/ornltm-style.sty

@@ -181,6 +181,7 @@
 # see http://texdoc.net/texmf-dist/doc/latex/pdfpages/pdfpages.pdf
 # and documents repo:
  'maketitle': r"\includepdf[pages=-]{flibcpp-tm-header.pdf}",
+ 'atendofbody': r"\includepdf[pages=-]{flibcpp-tm-footer.pdf}",
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
@@ -191,7 +192,7 @@
      author, 'howto'),
 ]
 
-latex_additional_files = glob.glob("_static/*")
+latex_additional_files = glob.glob("_static/*.sty")
 
 # -- Options for manual page output ------------------------------------------