Use environment variables in Doxyfile

Builds/CMake/RippledDocs.cmake

@@ -10,8 +10,7 @@ endif ()
 
 set (doxygen_output_directory "${CMAKE_BINARY_DIR}/docs/html")
 set (doxygen_index_file "${doxygen_output_directory}/index.html")
-set (doxyfile_in "${CMAKE_CURRENT_SOURCE_DIR}/docs/Doxyfile")
-set (doxyfile_out "${CMAKE_BINARY_DIR}/docs/Doxyfile")
+set (doxyfile "${CMAKE_CURRENT_SOURCE_DIR}/docs/Doxyfile")
 
 file (GLOB_RECURSE doxygen_input
   docs/*.md
@@ -24,7 +23,7 @@ list (APPEND doxygen_input
   README.md
   RELEASENOTES.md
   src/README.md)
-set (dependencies "${doxygen_input}" docs/Doxyfile)
+set (dependencies "${doxygen_input}" "${doxyfile}")
 
 find_path (doxygen_plantuml_jar_path plantuml.jar PATH_SUFFIXES share/plantuml)
 if (NOT doxygen_plantuml_jar_path)
@@ -51,15 +50,15 @@ add_custom_command (
   COMMAND "${CMAKE_COMMAND}" -P "${download_script}"
   WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/docs"
 )
-set (doxygen_tag_files "${tagfile}=http://en.cppreference.com/w/")
-
-# Substitute doxygen_output_directory.
-# TODO: Generate this file at build time, not configure time.
-configure_file ("${doxyfile_in}" "${doxyfile_out}" @ONLY)
+set (doxygen_tagfiles "${tagfile}=http://en.cppreference.com/w/")
 
 add_custom_command (
   OUTPUT "${doxygen_index_file}"
-  COMMAND "${DOXYGEN_EXECUTABLE}" "${doxyfile_out}"
+  COMMAND "${CMAKE_COMMAND}" -E env
+    "DOXYGEN_OUTPUT_DIRECTORY=${doxygen_output_directory}"
+    "DOXYGEN_TAGFILES=${doxygen_tagfiles}"
+    "DOXYGEN_PLANTUML_JAR_PATH=${doxygen_plantuml_jar_path}"
+    "${DOXYGEN_EXECUTABLE}" "${doxyfile}"
   WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}"
   DEPENDS "${dependencies}" "${tagfile}")
 add_custom_target (docs

bin/ci/ubuntu/build-and-test.sh

@@ -105,7 +105,7 @@ ${time} eval cmake --build . ${BUILDARGS} -- ${BUILDTOOLARGS}
 if [[ ${TARGET} == "docs" ]]; then
     ## mimic the standard test output for docs build
     ## to make controlling processes like jenkins happy
-    if [ -f html_doc/index.html ]; then
+    if [ -f docs/html/index.html ]; then
         echo "1 case, 1 test total, 0 failures"
     else
         echo "1 case, 1 test total, 1 failures"

docs/Dockerfile

@@ -26,8 +26,7 @@ RUN rm -rf /tmp/doxygen-1.8.14
 
 RUN mkdir -p /opt/plantuml
 RUN wget -O /opt/plantuml/plantuml.jar http://sourceforge.net/projects/plantuml/files/plantuml.jar/download
-ENV PLANTUML_JAR=/opt/plantuml/plantuml.jar
+ENV DOXYGEN_PLANTUML_JAR_PATH=/opt/plantuml/plantuml.jar
 
-RUN sed -i -e 's/@doxygen_output_directory@//' -e 's/@doxygen_tag_files@//' \
-      /opt/rippled/docs/Doxyfile
-CMD cd /opt/rippled/docs && doxygen Doxyfile
+ENV DOXYGEN_OUTPUT_DIRECTORY=html
+CMD cd /opt/rippled && doxygen docs/Doxyfile

docs/Doxyfile

@@ -7,7 +7,7 @@ PROJECT_NUMBER         =
 PROJECT_BRIEF          = C++ Library
 PROJECT_LOGO           =
 PROJECT_LOGO           = images/LogoForDocumentation.png
-OUTPUT_DIRECTORY       = @doxygen_output_directory@
+OUTPUT_DIRECTORY       = $(DOXYGEN_OUTPUT_DIRECTORY)
 CREATE_SUBDIRS         = NO
 ALLOW_UNICODE_NAMES    = NO
 OUTPUT_LANGUAGE        = English
@@ -299,7 +299,7 @@ SKIP_FUNCTION_MACROS   = YES
 #---------------------------------------------------------------------------
 # Configuration options related to external references
 #---------------------------------------------------------------------------
-TAGFILES               = @doxygen_tag_files@
+TAGFILES               = $(DOXYGEN_TAGFILES)
 GENERATE_TAGFILE       =
 ALLEXTERNALS           = NO
 EXTERNAL_GROUPS        = YES
@@ -336,7 +336,7 @@ DOT_PATH               =
 DOTFILE_DIRS           =
 MSCFILE_DIRS           =
 DIAFILE_DIRS           =
-PLANTUML_JAR_PATH      = @doxygen_plantuml_jar_path@
+PLANTUML_JAR_PATH      = $(DOXYGEN_PLANTUML_JAR_PATH)
 PLANTUML_INCLUDE_PATH  =
 DOT_GRAPH_MAX_NODES    = 50
 MAX_DOT_GRAPH_DEPTH    = 0

docs/README.md

@@ -1,11 +1,5 @@
 # Building documentation
 
-## Specifying Files
-
-To specify the source files for which to build documentation, modify `INPUT`
-and its related fields in `docs/Doxyfile`. Note that the `INPUT` paths are
-relative to the `docs/` directory.
-
 ## Install Dependencies
 
 ### Windows
@@ -30,7 +24,7 @@ Install these dependencies:
 
 ### [Optional] Install Plantuml (all platforms)
 
-Doxygen supports the optional use of [plantuml](http://plantuml.com) to 
+Doxygen supports the optional use of [plantuml](http://plantuml.com) to
 generate diagrams from `@startuml` sections. We don't currently rely on this
 functionality for docs, so it's largely optional. Requirements:
 
@@ -40,22 +34,28 @@ functionality for docs, so it's largely optional. Requirements:
    Set a system environment variable named `PLANTUML_JAR` with a value of the fullpath
    to the file system location of the `plantuml.jar` file you downloaded.
 
-## Do it
 
-### all platforms
+## Configuration
+
+You should set these environment variables:
+
+- `DOXYGEN_OUTPUT_DIRECTORY`
+- `DOXYGEN_PLANTUML_JAR_PATH`
+
+## Build
 
 From the rippled root folder:
+
 ```
-cd docs
-mkdir -p html_doc
-doxygen Doxyfile
+doxygen docs/Doxyfile
 ```
-The output will be in `docs/html_doc`.
+
+The output will be wherever you chose for `DOXYGEN_OUTPUT_DIRECTORY`.
 
 ## Docker
 
 (applicable to all platforms)
-    
+
 Instead of installing the doxygen tools locally, you can use the provided `Dockerfile` to create
 an ubuntu based image for running the tools:
 
@@ -72,5 +72,4 @@ Then to run the image, from the rippled root folder:
 sudo docker run -v $PWD:/opt/rippled --rm rippled-docs
 ```
 
-The output will be in `docs/html_doc`.
-
+The output will be in `html`.