Improve automatic documentation generation

This removes the need to edit the copyright year before generating the documentation (every year, in several files) and adds some technical information (doxygen generation date, doxygen version, and FLTK Git revision) in both HTML and PDF docs. - auto-generate copyright year (current year) used in several places - include FLTK Git revision in HTML and PDF docs - include generation date and doxygen version - replace special html footer which didn't work well with default footer
2022-08-10 18:51:53 +02:00 · 2022-08-10 18:51:53 +02:00 · ab61c03433
commit ab61c03433
parent b8c227a8f2
9 changed files with 106 additions and 52 deletions
--- a/documentation/CMakeLists.txt
+++ b/documentation/CMakeLists.txt
@ -1,7 +1,7 @@
 #
 # CMakeLists.txt to build docs for the FLTK project using CMake (www.cmake.org)
 #
-# Copyright 1998-2021 by Bill Spitzak and others.
+# Copyright 1998-2022 by Bill Spitzak and others.
 #
 # This library is free software. Distribution and use rights are outlined in
 # the file "COPYING" which should have been included with this file.  If this
@ -15,6 +15,11 @@
 #

 set (DOCS)
+set (GENERATE_DOCS FALSE)
+
+if (OPTION_BUILD_HTML_DOCUMENTATION OR OPTION_BUILD_PDF_DOCUMENTATION)
+  set (GENERATE_DOCS TRUE)
+endif ()

 if (OPTION_INCLUDE_DRIVER_DOCUMENTATION)
  set (DRIVER_DOCS "DriverDev")
@ -22,6 +27,57 @@ else ()
  set (DRIVER_DOCS "")
 endif ()

+#------------------------------------------------
+# generate files used for both HTML and PDF docs
+#------------------------------------------------
+
+if (GENERATE_DOCS)
+
+  # create required variables
+
+  execute_process (COMMAND date "+%Y"
+    OUTPUT_VARIABLE YEAR
+  )
+
+  # note: current locale is used for abbreviated month
+  execute_process (COMMAND date "+%b %d, %Y"
+    OUTPUT_VARIABLE CURRENT_DATE
+  )
+
+  execute_process (COMMAND git rev-parse --short=10 HEAD
+    OUTPUT_VARIABLE GIT_REVISION
+  )
+
+  # strip trailing newline
+  string (REPLACE "\n" "" GIT_REVISION ${GIT_REVISION})
+
+  execute_process (COMMAND doxygen --version
+    OUTPUT_VARIABLE DOXYGEN_VERSION_SHORT
+  )
+
+  # strip trailing git revision if doxygen was built from source
+  string (REGEX REPLACE " .*$" "" DOXYGEN_VERSION_SHORT ${DOXYGEN_VERSION_SHORT})
+
+  ## fl_debug_var (GIT_REVISION)
+  ## fl_debug_var (DOXYGEN_EXECUTABLE)
+  ## fl_debug_var (DOXYGEN_VERSION_SHORT)
+
+  # configure copyright.dox (includes current year)
+  configure_file (
+    ${CMAKE_CURRENT_SOURCE_DIR}/copyright.dox.in
+    ${CMAKE_CURRENT_BINARY_DIR}/copyright.dox
+    @ONLY
+  )
+
+  # configure generated.dox (includes date and versions)
+  configure_file (
+    ${CMAKE_CURRENT_SOURCE_DIR}/generated.dox.in
+    ${CMAKE_CURRENT_BINARY_DIR}/generated.dox
+    @ONLY
+  )
+
+endif (GENERATE_DOCS)
+
 #--------------------------
 # build html documentation
 #--------------------------
@ -36,12 +92,6 @@ if (OPTION_BUILD_HTML_DOCUMENTATION)
  set (GENERATE_LATEX NO)
  set (LATEX_HEADER   "")

-  configure_file (
-    ${CMAKE_CURRENT_SOURCE_DIR}/src/tiny.png
-    ${CMAKE_CURRENT_BINARY_DIR}/html/tiny.png
-    COPYONLY
-  )
-
  # configure Doxygen input file for HTML docs (Doxyfile.in)

  configure_file (
@ -87,10 +137,6 @@ if (OPTION_BUILD_PDF_DOCUMENTATION)
  # strip potential " (Git-hash)" from the original version
  string (REGEX REPLACE " .*$" "" DOXY_VERSION ${DOXYGEN_VERSION})

-  execute_process (COMMAND date +%Y
-    OUTPUT_VARIABLE YEAR
-  )
-
  # configure Doxygen input file for PDF docs (Doxybook.in)

  configure_file (
--- a/documentation/Doxyfile.in
+++ b/documentation/Doxyfile.in
@ -648,7 +648,8 @@ EXCLUDE_SYMBOLS  =
 # the \include command).

 EXAMPLE_PATH           = @CMAKE_CURRENT_SOURCE_DIR@/../test \
-                         @CMAKE_CURRENT_SOURCE_DIR@/../examples
+                         @CMAKE_CURRENT_SOURCE_DIR@/../examples \
+                         @CMAKE_CURRENT_BINARY_DIR@ @CMAKE_CURRENT_SOURCE_DIR@

 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
@ -803,7 +804,7 @@ HTML_HEADER            =
 # each generated HTML page. If it is left blank doxygen will generate a
 # standard footer.

-HTML_FOOTER            = @CMAKE_CURRENT_SOURCE_DIR@/src/html_footer
+HTML_FOOTER            =

 # The HTML_STYLESHEET tag can be used to specify a user-defined cascading
 # style sheet that is used by each HTML page. It can be used to
--- a/documentation/Makefile
+++ b/documentation/Makefile
@ -1,7 +1,7 @@
 #
 # Makefile for the Fast Light Tool Kit (FLTK) documentation.
 #
-# Copyright 1998-2020 by Bill Spitzak and others.
+# Copyright 1998-2022 by Bill Spitzak and others.
 #
 # This library is free software. Distribution and use rights are outlined in
 # the file "COPYING" which should have been included with this file.  If this
@ -67,6 +67,7 @@ dist:	docs

 clean:
 	$(RM) Doxyfile Doxybook
+	$(RM) copyright.dox generated.dox
 	$(RM) fltk.pdf refman.pdf src/fltk-book.tex src/fltk-book.tex.in
 	$(RMDIR) html latex
 	$(RM) *~ *.bck *.bak *.log
@ -131,24 +132,26 @@ uninstall-linux uninstall-osx:
 # Both files are generated from the common source file Doxyfile.in.
 # Note that Doxyfile.in is shared with CMake to configure these files.

-Doxyfile: Doxyfile.in
+Doxyfile: Doxyfile.in generated.dox copyright.dox
 	echo "Generating Doxyfile ..."
 	sed -e's,@FLTK_VERSION@,$(FLTK_VERSION),' \
 	    -e's,@GENERATE_HTML@,YES,' \
 	    -e's,@GENERATE_LATEX@,NO,' \
 	    -e's, @LATEX_HEADER@,,' \
-	    -e's,@CMAKE_CURRENT_SOURCE_DIR@/,,' \
-	    -e's,@FLTK_SOURCE_DIR@/,../,' \
+	    -e's,@CMAKE_CURRENT_SOURCE_DIR@,.,' \
+	    -e's,@CMAKE_CURRENT_BINARY_DIR@,,' \
+	    -e's,@FLTK_SOURCE_DIR@,..,' \
 	    < $< > $@

-Doxybook: Doxyfile.in
+Doxybook: Doxyfile.in generated.dox copyright.dox
 	echo "Generating Doxybook ..."
 	sed -e's,@FLTK_VERSION@,$(FLTK_VERSION),' \
 	    -e's,@GENERATE_HTML@,NO,' \
 	    -e's,@GENERATE_LATEX@,YES,' \
 	    -e's,@LATEX_HEADER@,src/fltk-book.tex,' \
-	    -e's,@CMAKE_CURRENT_SOURCE_DIR@/,,' \
-	    -e's,@FLTK_SOURCE_DIR@/,../,' \
+	    -e's,@CMAKE_CURRENT_SOURCE_DIR@,.,' \
+	    -e's,@CMAKE_CURRENT_BINARY_DIR@,,' \
+	    -e's,@FLTK_SOURCE_DIR@,..,' \
 	    < $< > $@

 # The HTML files are generated using doxygen, and this needs
@ -164,7 +167,6 @@ html:	$(HTMLFILES) Doxyfile
 	if test "x$(DOXYDOC)" = "x" ; then \
 	  echo "Sorry - doxygen not found. Please install doxygen and run configure."; \
 	fi
-	test -d html && cp src/tiny.png html/

 # The PDF documentation (fltk.pdf) is generated using doxygen and LaTeX, and
 # this needs installed Doxygen and LaTeX programs and may take some time, so
@ -191,4 +193,23 @@ src/fltk-book.tex: src/fltk-book.tex.in

 src/fltk-book.tex.in: src/fltk-title.tex.in
 	echo "Generating $@ ..."
-	./make_header src/fltk-title.tex.in src/fltk-book.tex.in
+	GIT_REVISION=`git rev-parse --short=10 HEAD`; \
+	./make_header $< $@; \
+	sed -i -e"s/@GIT_REVISION@/$$GIT_REVISION/g" $@
+
+
+generated.dox: generated.dox.in
+	echo "Generating $@ ..."
+	CURRENT_DATE=`date "+%b %d, %Y"`; \
+	GIT_REVISION=`git rev-parse --short=10 HEAD`; \
+	DOXYGEN_VERSION_SHORT=`$(DOXYDOC) --version|cut -f1 -d' '`; \
+	sed -e"s/@CURRENT_DATE@/$$CURRENT_DATE/g" \
+	    -e"s/@GIT_REVISION@/$$GIT_REVISION/g" \
+	    -e"s/@DOXYGEN_VERSION_SHORT@/$$DOXYGEN_VERSION_SHORT/g" \
+	    < $< > $@
+
+copyright.dox: copyright.dox.in
+	echo "Generating $@ ..."
+	YEAR=`date +%Y`; \
+	sed -e"s/@YEAR@/$$YEAR/g" \
+	    < $< > $@
--- a/documentation/copyright.dox.in
+++ b/documentation/copyright.dox.in
@ -0,0 +1 @@
+Copyright &copy; 1998 - @YEAR@ by Bill Spitzak and others.
--- a/documentation/generated.dox.in
+++ b/documentation/generated.dox.in
@ -0,0 +1,6 @@
+<br>
+<small>
+  Generated on @CURRENT_DATE@
+  from Git revision @GIT_REVISION@
+  by Doxygen @DOXYGEN_VERSION_SHORT@
+</small>
--- a/documentation/src/fltk-title.tex.in
+++ b/documentation/src/fltk-title.tex.in
@ -14,7 +14,7 @@
 By F. Costantini, D. Gibson, M. Melcher, \\
 A. Schlosser, B. Spitzak, and M. Sweet.}\\
 \vspace*{1.5cm}
-{\large Copyright 1998-@YEAR@ by Bill Spitzak and others.}\\
+{\large Copyright © 1998 - @YEAR@ by Bill Spitzak and others.}\\
 \vspace*{0.75cm}
 {\small
 This software and manual are provided under the terms of the GNU Library General Public License.}\\
@ -22,10 +22,12 @@ This software and manual are provided under the terms of the GNU Library General
 Permission is granted to reproduce this manual or any portion for any purpose,}\\
 {\small
 provided this copyright and permission notice are preserved.}\\
-\vspace*{2.5cm}
+\vspace*{1.5cm}
 {\large Generated by Doxygen @DOXY_VERSION@}\\
 \vspace*{0.5cm}
 \today{}\\
+\vspace*{0.5cm}
+{\small Git revision @GIT_REVISION@}\\
 \end{center}
 \end{titlepage}
 %
--- a/documentation/src/html_footer
+++ b/documentation/src/html_footer
@ -1,24 +0,0 @@
-<!--BEGIN GENERATE_TREEVIEW-->
-    <li class="footer">
-      <!-- Generated for $projectname by Doxygen -->
-      Copyright &copy; 1998-2022 by Bill Spitzak and others. &nbsp;&nbsp;&nbsp;
-      <a href="https://www.fltk.org"><img src="tiny.png" align="bottom" alt="FLTK"></a>
-     </li>
-   </ul>
- </div>
-<!--END GENERATE_TREEVIEW-->
-<!--BEGIN !GENERATE_TREEVIEW-->
-<hr class="footer"/><address class="footer"><small>
-    <!-- Generated for $projectname by Doxygen -->
-    Copyright &copy; 1998-2022 by Bill Spitzak and others. &nbsp;&nbsp;&nbsp;
-    <a href="https://www.fltk.org"><img src="tiny.png" align="bottom" alt="FLTK"></a>
-</small></address>
-<hr class="footer"/><address class="footer"><small>
-  <div align="center">
-    Permission is granted to reproduce this manual or any portion for any purpose,
-    provided this copyright and permission notice are preserved.
-  </div>
-</small></address>
-<!--END !GENERATE_TREEVIEW-->
-</body>
-</html>
--- a/documentation/src/index.dox
+++ b/documentation/src/index.dox
@ -13,13 +13,13 @@
    By F.&nbsp;Costantini, D.&nbsp;Gibson, M.&nbsp;Melcher,
    A.&nbsp;Schlosser, B.&nbsp;Spitzak and M.&nbsp;Sweet.

-    Copyright &copy; 1998-2022 by Bill Spitzak and others.
+    \include{doc} copyright.dox
  </CENTER></TD>
 </TR>
 </TABLE>
 <TABLE BGCOLOR="#9f9f9f" CELLPADDING="8" CELLSPACING="0" SUMMARY="TITLE BAR" WIDTH="100%" BORDER="0">
 <TR>
-  <TD>
+  <TD style="text-align: center;">
    This software and manual are provided under the terms of the GNU
    Library General Public License. Permission is granted to reproduce
    this manual or any portion for any purpose, provided this copyright
@ -103,6 +103,7 @@
 </TR>
 </TABLE>

+\htmlinclude{doc} generated.dox

 \htmlonly
 <hr>
--- a/documentation/src/preface.dox
+++ b/documentation/src/preface.dox
@ -80,8 +80,8 @@ was dropped after FLTK 1.0.10. FLTK uses the preprocessor definition

 \section preface_copyrights Copyrights and Trademarks

-FLTK is Copyright 1998-2020 by Bill Spitzak and others.  Use and
-distribution of FLTK is governed by the GNU Library General Public
+FLTK is \include{doc} copyright.dox
+Use and distribution of FLTK is governed by the GNU Library General Public
 License with 4 exceptions, located in \ref license.

 UNIX is a registered trademark of the X Open Group, Inc.
				`@ -0,0 +1 @@`
				`Copyright © 1998 - @YEAR@ by Bill Spitzak and others.`