Permalink
Browse files

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!
  • Loading branch information...
1 parent 4de4dc9 commit ee9bfeb67316ceec746a6b780237ea96f2861a36 Keith Derrick committed Apr 19, 2012
Showing with 3,540 additions and 188 deletions.
  1. +22 −4 .gitignore
  2. +25 −5 README.md
  3. +0 −174 doc/Doxyfile
  4. +0 −5 doc/create_docs.sh
  5. +1 −0 src/CMakeLists.txt
  6. +49 −0 src/doc/CMakeLists.txt
  7. +1,707 −0 src/doc/Doxyfile.client.in
  8. +1,707 −0 src/doc/Doxyfile.modules.in
  9. +29 −0 src/doc/README_FIRST.md
View
@@ -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
View
@@ -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
View
@@ -1,174 +0,0 @@
-# Doxyfile 0.1
-
-#---------------------------------------------------------------------------
-# General configuration options
-#---------------------------------------------------------------------------
-PROJECT_NAME = NYX
-PROJECT_NUMBER = 2.0.0
-OUTPUT_DIRECTORY = .
-OUTPUT_LANGUAGE = English
-EXTRACT_ALL = NO
-EXTRACT_PRIVATE = YES
-EXTRACT_STATIC = YES
-EXTRACT_LOCAL_CLASSES = NO
-EXTRACT_LOCAL_METHODS = NO
-HIDE_UNDOC_MEMBERS = YES
-HIDE_UNDOC_CLASSES = YES
-BRIEF_MEMBER_DESC = YES
-REPEAT_BRIEF = YES
-ALWAYS_DETAILED_SEC = NO
-FULL_PATH_NAMES = NO
-STRIP_FROM_PATH =
-INTERNAL_DOCS = YES
-STRIP_CODE_COMMENTS = YES
-CASE_SENSE_NAMES = YES
-SHORT_NAMES = NO
-HIDE_SCOPE_NAMES = NO
-VERBATIM_HEADERS = YES
-SHOW_INCLUDE_FILES = YES
-JAVADOC_AUTOBRIEF = YES
-INHERIT_DOCS = YES
-INLINE_INFO = YES
-SORT_MEMBER_DOCS = YES
-SORT_GROUP_NAMES = YES
-DISTRIBUTE_GROUP_DOC = NO
-TAB_SIZE = 4
-GENERATE_TODOLIST = NO
-GENERATE_TESTLIST = NO
-GENERATE_BUGLIST = NO
-ALIASES =
-ENABLED_SECTIONS =
-MAX_INITIALIZER_LINES = 30
-OPTIMIZE_OUTPUT_FOR_C = YES
-SHOW_USED_FILES = NO
-#---------------------------------------------------------------------------
-# configuration options related to warning and progress messages
-#---------------------------------------------------------------------------
-QUIET = YES
-WARNINGS = YES
-WARN_IF_UNDOCUMENTED = YES
-WARN_FORMAT =
-WARN_LOGFILE =
-#---------------------------------------------------------------------------
-# configuration options related to the input files
-#---------------------------------------------------------------------------
-INPUT = ../include/nyx
-FILE_PATTERNS = *.c *.h
-RECURSIVE = YES
-EXCLUDE =
-EXCLUDE_PATTERNS =
-
-# The EXAMPLE_PATH tag can be used to specify one or more files or
-# directories that contain example code fragments that are included (see
-# the \include command).
-
-EXAMPLE_PATH =
-EXAMPLE_PATTERNS =
-EXAMPLE_RECURSIVE = NO
-IMAGE_PATH =
-INPUT_FILTER =
-FILTER_SOURCE_FILES = NO
-#---------------------------------------------------------------------------
-# configuration options related to source browsing
-#---------------------------------------------------------------------------
-SOURCE_BROWSER = YES
-INLINE_SOURCES = NO
-REFERENCED_BY_RELATION = YES
-REFERENCES_RELATION = YES
-#---------------------------------------------------------------------------
-# configuration options related to the alphabetical class index
-#---------------------------------------------------------------------------
-ALPHABETICAL_INDEX = NO
-COLS_IN_ALPHA_INDEX = 5
-IGNORE_PREFIX =
-#---------------------------------------------------------------------------
-# configuration options related to the HTML output
-#---------------------------------------------------------------------------
-GENERATE_HTML = YES
-HTML_OUTPUT =
-HTML_HEADER =
-HTML_FOOTER =
-HTML_STYLESHEET =
-HTML_ALIGN_MEMBERS = YES
-GENERATE_HTMLHELP = NO
-GENERATE_CHI = NO
-BINARY_TOC = NO
-TOC_EXPAND = NO
-DISABLE_INDEX = NO
-ENUM_VALUES_PER_LINE = 1
-GENERATE_TREEVIEW = YES
-TREEVIEW_WIDTH = 250
-#---------------------------------------------------------------------------
-# configuration options related to the LaTeX output
-#---------------------------------------------------------------------------
-GENERATE_LATEX = NO
-LATEX_OUTPUT =
-COMPACT_LATEX = NO
-PAPER_TYPE = a4wide
-EXTRA_PACKAGES =
-LATEX_HEADER =
-PDF_HYPERLINKS = NO
-USE_PDFLATEX = NO
-LATEX_BATCHMODE = NO
-#---------------------------------------------------------------------------
-# configuration options related to the RTF output
-#---------------------------------------------------------------------------
-GENERATE_RTF = NO
-RTF_OUTPUT =
-COMPACT_RTF = NO
-RTF_HYPERLINKS = NO
-RTF_STYLESHEET_FILE =
-RTF_EXTENSIONS_FILE =
-#---------------------------------------------------------------------------
-# configuration options related to the man page output
-#---------------------------------------------------------------------------
-GENERATE_MAN = NO
-MAN_OUTPUT = man
-MAN_EXTENSION = .3
-MAN_LINKS = YES
-#---------------------------------------------------------------------------
-# configuration options related to the XML output
-#---------------------------------------------------------------------------
-GENERATE_XML = NO
-#---------------------------------------------------------------------------
-# Configuration options related to the preprocessor
-#---------------------------------------------------------------------------
-ENABLE_PREPROCESSING = YES
-MACRO_EXPANSION = YES
-EXPAND_ONLY_PREDEF = YES
-SEARCH_INCLUDES = YES
-INCLUDE_PATH = ../include/nyx
-INCLUDE_FILE_PATTERNS = *.h
-PREDEFINED =
-SKIP_FUNCTION_MACROS = YES
-#---------------------------------------------------------------------------
-# Configuration::addtions related to external references
-#---------------------------------------------------------------------------
-TAGFILES =
-GENERATE_TAGFILE =
-ALLEXTERNALS = NO
-PERL_PATH =
-#---------------------------------------------------------------------------
-# Configuration options related to the dot tool
-#---------------------------------------------------------------------------
-CLASS_DIAGRAMS = YES
-HAVE_DOT = YES
-DOT_TRANSPARENT = YES
-CALL_GRAPH = YES
-CLASS_GRAPH = YES
-GROUP_GRAPHS = YES
-COLLABORATION_GRAPH = YES
-TEMPLATE_RELATIONS = YES
-HIDE_UNDOC_RELATIONS = YES
-INCLUDE_GRAPH = YES
-INCLUDED_BY_GRAPH = YES
-GRAPHICAL_HIERARCHY = YES
-GENERATE_LEGEND = YES
-DOT_PATH =
-DOTFILE_DIRS =
-GENERATE_LEGEND = YES
-DOT_CLEANUP = YES
-#---------------------------------------------------------------------------
-# Configuration::addtions related to the search engine
-#---------------------------------------------------------------------------
-SEARCHENGINE = YES
View
@@ -1,5 +0,0 @@
-#!/bin/sh
-
-echo "Generating doxygen docs..."
-doxygen ./Doxyfile &> /dev/null
-echo "Done!"
View
@@ -97,3 +97,4 @@ message("NYX_MODULE_SUFFIX set to ${CMAKE_SHARED_MODULE_SUFFIX}")
include(lib.cmake)
+add_subdirectory(doc)
View
@@ -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} )
Oops, something went wrong.

0 comments on commit ee9bfeb

Please sign in to comment.