From ab61c03433423d1744db3550db8e1e281dbdf256 Mon Sep 17 00:00:00 2001 From: Albrecht Schlosser Date: Wed, 10 Aug 2022 18:51:53 +0200 Subject: [PATCH] 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 --- documentation/CMakeLists.txt | 68 ++++++++++++++++++++++++----- documentation/Doxyfile.in | 5 ++- documentation/Makefile | 39 +++++++++++++---- documentation/copyright.dox.in | 1 + documentation/generated.dox.in | 6 +++ documentation/src/fltk-title.tex.in | 6 ++- documentation/src/html_footer | 24 ---------- documentation/src/index.dox | 5 ++- documentation/src/preface.dox | 4 +- 9 files changed, 106 insertions(+), 52 deletions(-) create mode 100644 documentation/copyright.dox.in create mode 100644 documentation/generated.dox.in delete mode 100644 documentation/src/html_footer diff --git a/documentation/CMakeLists.txt b/documentation/CMakeLists.txt index 41ed62961..1fe6d615e 100644 --- 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 ( diff --git a/documentation/Doxyfile.in b/documentation/Doxyfile.in index 0c6f8ffac..227c4b6fe 100644 --- 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 diff --git a/documentation/Makefile b/documentation/Makefile index 8fc0ca77c..3ecd63700 100644 --- 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" \ + < $< > $@ diff --git a/documentation/copyright.dox.in b/documentation/copyright.dox.in new file mode 100644 index 000000000..990de8844 --- /dev/null +++ b/documentation/copyright.dox.in @@ -0,0 +1 @@ +Copyright © 1998 - @YEAR@ by Bill Spitzak and others. diff --git a/documentation/generated.dox.in b/documentation/generated.dox.in new file mode 100644 index 000000000..9ab6987e0 --- /dev/null +++ b/documentation/generated.dox.in @@ -0,0 +1,6 @@ +
+ + Generated on @CURRENT_DATE@ + from Git revision @GIT_REVISION@ + by Doxygen @DOXYGEN_VERSION_SHORT@ + diff --git a/documentation/src/fltk-title.tex.in b/documentation/src/fltk-title.tex.in index 1bc388828..c4c7c1813 100644 --- 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} % diff --git a/documentation/src/html_footer b/documentation/src/html_footer deleted file mode 100644 index 03c6717a5..000000000 --- a/documentation/src/html_footer +++ /dev/null @@ -1,24 +0,0 @@ - -
  • - - Copyright © 1998-2022 by Bill Spitzak and others.     - FLTK -
    • - - - - -
    - - Copyright © 1998-2022 by Bill Spitzak and others.     - FLTK -
    -
    -
    - Permission is granted to reproduce this manual or any portion for any purpose, - provided this copyright and permission notice are preserved. -
    -
    - - - diff --git a/documentation/src/index.dox b/documentation/src/index.dox index 97e89eab6..7d3858d57 100644 --- a/documentation/src/index.dox +++ b/documentation/src/index.dox @@ -13,13 +13,13 @@ By F. Costantini, D. Gibson, M. Melcher, A. Schlosser, B. Spitzak and M. Sweet. - Copyright © 1998-2022 by Bill Spitzak and others. + \include{doc} copyright.dox -
    + 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 @@
    +\htmlinclude{doc} generated.dox \htmlonly
    diff --git a/documentation/src/preface.dox b/documentation/src/preface.dox index f3f401efa..168240570 100644 --- 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.