Merge pull request ESMCI#1385 from NCAR/ejh_autotools_docs

now build docs for autotools build

Makefile.am

@@ -2,9 +2,14 @@
 
 # Ed Hartnett
 
-SUBDIRS = src tests examples
-
 # Look in the m4 directory for autotools stuff.
 ACLOCAL_AMFLAGS= -I m4
 
+# Does the user want to build fortran?
+if BUILD_DOCS
+DOC = doc
+endif
+
+SUBDIRS = src tests examples ${DOC}
+
 EXTRA_DIST = CMakeLists.txt set_flags.am

configure.ac

@@ -2,10 +2,20 @@
 ## Ed Hartnett 8/16/17
 
 # Initialize autoconf and automake.
-AC_INIT(pio, 2.4.0)
+AC_INIT(pio, 2.4.1)
 AC_CONFIG_SRCDIR(src/clib/pio_darray.c)
 AM_INIT_AUTOMAKE([foreign serial-tests])
 
+# The PIO version, again.
+AC_DEFINE([PIO_VERSION_MAJOR], [2], [PIO major version])
+AC_DEFINE([PIO_VERSION_MINOR], [4], [PIO minor version])
+AC_DEFINE([PIO_VERSION_PATCH], [1], [PIO patch version])
+
+# Once more for the documentation.
+AC_SUBST([VERSION_MAJOR], [2])
+AC_SUBST([VERSION_MINOR], [4])
+AC_SUBST([VERSION_PATCH], [1])
+
 # The m4 directory holds macros for autoconf.
 AC_CONFIG_MACRO_DIR([m4])
 
@@ -41,7 +51,6 @@ if test "x$enable_logging" = xyes; then
    AC_DEFINE([PIO_ENABLE_LOGGING], 1, [If true, turn on logging.])
 fi
 
-
 # Does the user want to enable Fortran library?
 AC_MSG_CHECKING([whether Fortran library should be build])
 AC_ARG_ENABLE([fortran],
@@ -60,14 +69,32 @@ test "x$enable_pnetcdf" = xno || enable_pnetcdf=yes
 AC_MSG_RESULT([$enable_pnetcdf])
 AM_CONDITIONAL(BUILD_PNETCDF, [test "x$enable_pnetcdf" = xyes])
 
+# Does the user want to build documentation?
+AC_MSG_CHECKING([whether documentation should be build (requires doxygen)])
+AC_ARG_ENABLE([docs],
+              [AS_HELP_STRING([--enable-docs],
+                              [enable building of documentation with doxygen.])])
+test "x$enable_docs" = xyes || enable_docs=no
+AC_MSG_RESULT([$enable_docs])
+AM_CONDITIONAL(BUILD_DOCS, [test "x$enable_docs" = xyes])
+
+# Is doxygen installed?
+AC_CHECK_PROGS([DOXYGEN], [doxygen])
+if test -z "$DOXYGEN" -a test "x$enable_docs" = xyes; then
+   AC_MSG_ERROR([Doxygen not found but --enable-docs used.])
+fi
+
+# If building docs, process Doxyfile.in into Doxyfile.
+if test "x$enable_docs" = xyes; then
+   AC_SUBST([CMAKE_CURRENT_SOURCE_DIR], ["."])
+   AC_SUBST([CMAKE_BINARY_DIR], [".."])
+   AC_SUBST([C_SRC_FILES], ["../src/clib/pio_nc4.c"])
+   AC_CONFIG_FILES([doc/Doxyfile])
+fi
+
 # NetCDF (at least classic) is required for PIO to build.
 AC_DEFINE([_NETCDF], [1], [netCDF classic library available])
 
-# The PIO version, again.
-AC_DEFINE([PIO_VERSION_MAJOR], [2], [PIO major version])
-AC_DEFINE([PIO_VERSION_MINOR], [4], [PIO minor version])
-AC_DEFINE([PIO_VERSION_PATCH], [0], [PIO patch version])
-
 # ????
 AC_DEFINE([CPRGNU], [1], [defined by CMake build])
 
@@ -143,5 +170,6 @@ AC_OUTPUT(Makefile
           tests/unit/Makefile
           tests/general/Makefile
           tests/general/util/Makefile
+          doc/Makefile
           examples/Makefile
           examples/c/Makefile)

doc/Doxyfile.in

@@ -58,7 +58,7 @@ PROJECT_LOGO           =
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = ../..
+OUTPUT_DIRECTORY       = ..
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
 # directories (in 2 levels) under the output directory of each output format and
@@ -768,7 +768,7 @@ WARN_LOGFILE           =
 # spaces.
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/source \
+INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/../doc/source \
                          @CMAKE_CURRENT_SOURCE_DIR@/../src/flib \
                          @CMAKE_CURRENT_SOURCE_DIR@/../examples/c \
                          @CMAKE_CURRENT_SOURCE_DIR@/../examples/f03 \
@@ -1113,7 +1113,8 @@ HTML_STYLESHEET        =
 # list). For an example see the documentation.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_EXTRA_STYLESHEET  = ../../docs/customdoxygen.css
+#HTML_EXTRA_STYLESHEET  = ../../docs/customdoxygen.css
+HTML_EXTRA_STYLESHEET  = customdoxygen.css
 
 # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
 # other source files which should be copied to the HTML output directory. Note

doc/Makefile.am

@@ -0,0 +1,15 @@
+# This is part of PIO. It creates the doc Makefile.
+
+# Ed Hartnett 4/1/19
+
+EXTRA_DIST = CMakeLists.txt customdoxygen.css Doxyfile.in	\
+DoxygenLayout.xml doxygen.sty
+
+# simple doxygen target
+all:
+	doxygen Doxyfile
+
+# clean up the extras including doxygen
+#clean-local:
+#	cd ${top_srcdir}
+#	rm -rf doxygen

docs/_c_a_mexample.html

@@ -23,7 +23,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">PIO
-   &#160;<span id="projectnumber">2.4.0</span>
+   &#160;<span id="projectnumber">2.4.1</span>
    </div>
   </td>
  </tr>
@@ -107,7 +107,7 @@ <h1><a class="anchor" id="Init"></a>
 </div></div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Fri Feb 8 2019 13:02:31 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Mon Apr 1 2019 08:48:42 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>

docs/annotated.html

@@ -23,7 +23,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">PIO
-   &#160;<span id="projectnumber">2.4.0</span>
+   &#160;<span id="projectnumber">2.4.1</span>
    </div>
   </td>
  </tr>
@@ -101,20 +101,12 @@
 <tr id="row_5_1_" class="even"><td class="entry"><span style="width:32px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="interfacepionfput__mod_1_1_p_i_oc__put__vara__float.html" target="_self">PIOc_put_vara_float</a></td><td class="desc"></td></tr>
 <tr id="row_5_2_"><td class="entry"><span style="width:32px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="interfacepionfput__mod_1_1_p_i_oc__put__vara__int.html" target="_self">PIOc_put_vara_int</a></td><td class="desc"></td></tr>
 <tr id="row_5_3_" class="even"><td class="entry"><span style="width:32px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="interfacepionfput__mod_1_1_p_i_oc__put__vara__text.html" target="_self">PIOc_put_vara_text</a></td><td class="desc"></td></tr>
-<tr id="row_6_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="structfile__desc__t.html" target="_self">file_desc_t</a></td><td class="desc">File descriptor structure </td></tr>
-<tr id="row_7_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="structio__desc__t.html" target="_self">io_desc_t</a></td><td class="desc">IO descriptor structure </td></tr>
-<tr id="row_8_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="structio__region.html" target="_self">io_region</a></td><td class="desc">IO region structure </td></tr>
-<tr id="row_9_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="structiosystem__desc__t.html" target="_self">iosystem_desc_t</a></td><td class="desc">IO system descriptor structure </td></tr>
-<tr id="row_10_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="structrearr__comm__fc__opt.html" target="_self">rearr_comm_fc_opt</a></td><td class="desc">Rearranger comm flow control options </td></tr>
-<tr id="row_11_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="structrearr__opt.html" target="_self">rearr_opt</a></td><td class="desc">Rearranger options </td></tr>
-<tr id="row_12_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="structvar__desc__t.html" target="_self">var_desc_t</a></td><td class="desc">Variable description structure </td></tr>
-<tr id="row_13_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="structwmulti__buffer.html" target="_self">wmulti_buffer</a></td><td class="desc">The multi buffer holds data from one or more variables </td></tr>
 </table>
 </div><!-- directory -->
 </div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Fri Feb 8 2019 13:02:31 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Mon Apr 1 2019 08:48:43 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>

docs/api.html

@@ -23,7 +23,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">PIO
-   &#160;<span id="projectnumber">2.4.0</span>
+   &#160;<span id="projectnumber">2.4.1</span>
    </div>
   </td>
  </tr>
@@ -149,7 +149,7 @@ <h2><a class="anchor" id="inqnc"></a>
 </div></div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Fri Feb 8 2019 13:02:31 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Mon Apr 1 2019 08:48:42 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>

docs/contributing_code.html

@@ -23,7 +23,7 @@
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">PIO
-   &#160;<span id="projectnumber">2.4.0</span>
+   &#160;<span id="projectnumber">2.4.1</span>
    </div>
   </td>
  </tr>
@@ -94,7 +94,7 @@ <h2>Indentation and Spacing</h2>
 </div></div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Fri Feb 8 2019 13:02:31 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Mon Apr 1 2019 08:48:42 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>