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
This commit is contained in:
Albrecht Schlosser 2022-08-10 18:51:53 +02:00
parent b8c227a8f2
commit ab61c03433
9 changed files with 106 additions and 52 deletions

View File

@ -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 (

View File

@ -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

View File

@ -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" \
< $< > $@

View File

@ -0,0 +1 @@
Copyright &copy; 1998 - @YEAR@ by Bill Spitzak and others.

View File

@ -0,0 +1,6 @@
<br>
<small>
Generated on @CURRENT_DATE@
from Git revision @GIT_REVISION@
by Doxygen @DOXYGEN_VERSION_SHORT@
</small>

View File

@ -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}
%

View File

@ -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>

View File

@ -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>

View File

@ -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.