Configure and Reorganize Documentation Generation

- Use configure_file() to configure the project name, version, and
paths in the doxygen input files.
- Add a make target for docs, allowing create_docs.sh to be deleted.
- Move doxygen input files under the src directory and add
CMakeLists.txt to configure them,
- Remove the contents of the original doc directory.
- Modify the README file with new instructions for generating docs.
- Add a README_FIRST to src/doc to cover the possibility that doxywizard
or some other tool may strip the license information from the files.
- Split the generated documentation to reflect the different client and
module APIs.
- In keeping with supporting out-of-tree builds, documentation is generated
under doc/ in the build directory. But the user can override this on the
cmake command line.
- Updated the .gitignore file with a license block, and modified the list of
files - including other variants for the build directory name and the
original doc/ directory in the project root.
- Note the prepending of a "/" to directory names in .gitignore. This
stops the directories being ignored in subdirectories. Ignoring /doc
in the root also ignored /src/doc!

.gitignore

@@ -1,3 +1,21 @@
+# @@@LICENSE
+#
+#      Copyright (c) 2010-2012 Hewlett-Packard Development Company, L.P.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# LICENSE@@@
+
 cscope.out
 *.so
 *.o
@@ -6,13 +24,13 @@ cscope.out
 .cscope.files
 .sc_status
 *.swp
-Debug/
+/Debug
 .project
 .cproject
 /patches
-build*
-BUILD-*
-doc/html
+/build*
+/BUILD*
+/doc
 *.DS_Store
 include/nyx/common/nyx_version.h
 src/config/nyx_config.h

README.md

@@ -54,18 +54,38 @@ directory.
 
 ## Generating documentation
 
+Nyx generates two sets of documentation, reflecting that fact that it the APIs it presents to 
+application and module writers are different.
+
 The tool required to generate the documentation is:
 
 * doxygen 1.6.3
+* graphviz 2.20.2 
+
+Once you have run cmake, execute the following to generate the documentation:
+
+$ make docs
+
+To view the generated HTML documentation, point your browser to either of the following
+
+    doc/module_api/html/index.html
+    doc/client_api/html/index.html
 
-Once you have downloaded the source, execute the following to generate the documentation:
+in your build directory.
 
-    $ cd doc
-    $ ./create_docs.sh
+Just as you can do out-of-tree builds, Nyx allows you to place the documentation files anywhere
+you wish by overriding the NYX_DOC_LOCATION variable on the cmake command line. For example, 
 
-To view the generated HTML documentation, point your browser to 
+    $ cmake -D NYX_DOC_LOCATION:PATH=$HOME/documentation/nyx-lib ..
+    $ make docs
+
+will place the documentation directories (module_api and client_api) under the 
+
+    $HOME/documentation/nyx-lib 
+
+directory.
 
-    doc/html/index.html
+The provided path may be absolute or relative. Relative paths are 'relative' to the build directory.
 
 # Copyright and License Information
 

src/CMakeLists.txt

@@ -97,3 +97,4 @@ message("NYX_MODULE_SUFFIX   set to ${CMAKE_SHARED_MODULE_SUFFIX}")
 
 include(lib.cmake)
 
+add_subdirectory(doc)

src/doc/CMakeLists.txt

@@ -0,0 +1,49 @@
+# @@@LICENSE
+#
+#      Copyright (c) 2010-2012 Hewlett-Packard Development Company, L.P.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# LICENSE@@@
+
+# Allow developers to define NYX_DOC_LOCATION, and thus specify the
+# root directory under which all documentation will be placed.
+
+if (NOT NYX_DOC_LOCATION)
+    set(NYX_DOC_LOCATION "${CMAKE_BINARY_DIR}/doc")
+else()
+# Make sure relative paths are relative to the binary directory, not
+# this source directory.
+    if (NOT IS_ABSOLUTE "${NYX_DOC_LOCATION}")
+        set (NYX_DOC_LOCATION "${CMAKE_BINARY_DIR}/${NYX_DOC_LOCATION}")
+    endif()
+endif()
+
+set(NYX_DOC_LOCATION "${NYX_DOC_LOCATION}" CACHE PATH "The directory in which documentation will be created")
+
+message("")
+message(STATUS "-- ${CMAKE_PROJECT_NAME} documentation will be created in ${NYX_DOC_LOCATION}")
+message("")
+
+# Create the doxygen input files with all the correct paths etc.
+
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.modules.in ${NYX_DOC_LOCATION}/Doxyfile.modules @ONLY)
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.client.in ${NYX_DOC_LOCATION}/Doxyfile.client @ONLY)
+
+# Add a target called "docs" (i.e., make docs). 
+# doxygen and dot (from graphviz) are expected to be available.
+add_custom_target(docs 
+                  doxygen ./Doxyfile.modules
+                  COMMAND doxygen ./Doxyfile.client
+                  SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.client.in ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.modules.in
+                  WORKING_DIRECTORY ${NYX_DOC_LOCATION} )