Skip to content
Browse files

Merge pull request #50 from nyx-project/autoconfigure_and_split_docum…

…entation

Configure and Reorganize Documentation Generation
  • Loading branch information...
2 parents 60c8a43 + ee9bfeb commit 41267f0dd25d281bf993377223a9c80905702bbd Keith Derrick committed Jun 7, 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
26 .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
View
30 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
View
174 doc/Doxyfile
@@ -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
5 doc/create_docs.sh
@@ -1,5 +0,0 @@
-#!/bin/sh
-
-echo "Generating doxygen docs..."
-doxygen ./Doxyfile &> /dev/null
-echo "Done!"
View
1 src/CMakeLists.txt
@@ -97,3 +97,4 @@ message("NYX_MODULE_SUFFIX set to ${CMAKE_SHARED_MODULE_SUFFIX}")
include(lib.cmake)
+add_subdirectory(doc)
View
49 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} )
View
1,707 src/doc/Doxyfile.client.in
1,707 additions, 0 deletions not shown because the diff is too large. Please use a local Git client to view these changes.
View
1,707 src/doc/Doxyfile.modules.in
1,707 additions, 0 deletions not shown because the diff is too large. Please use a local Git client to view these changes.
View
29 src/doc/README_FIRST.md
@@ -0,0 +1,29 @@
+# Editing the .in Files
+
+While *doxywizard* makes it easy to edit these files, be aware that - on saving - it regenerates
+the files from scratch. In the process, it removes any additional comments.
+
+**Primarily, this means that the copyright and licensing information will be stripped from the files.**
+
+Should the files *Doxyfile.client.in* and/or *Doxyfile.modules.in* be missing their copyright or
+licensing information, the following notice applies regardless.
+
+# Copyright and License Information
+
+All content, including all source code files and documentation files in this repository are:
+
+ Copyright (c) 2010-2012 Hewlett-Packard Development Company, L.P.
+
+All content, including all source code files and documentation files in this repository are:
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this content 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.
+

0 comments on commit 41267f0

Please sign in to comment.
Something went wrong with that request. Please try again.