Merge pull request #61 from OpenSimulationInterface/feature/add-doxygen-doc

Resolve issue #38 (doxygen documentation)

Author: jdsika

.gitignore

@@ -11,4 +11,6 @@ CTestTestfile.cmake
 build
 *.egg-info
 osi
-.project
+.project
+doc/html
+doc/latex

CMakeLists.txt

@@ -1,6 +1,11 @@
 cmake_minimum_required(VERSION 3.7)
 
+# set name and version of the project 
 project(open_simulation_interface)
+set(VERSION_MAJOR 2)
+set(VERSION_MINOR 1)
+set(VERSION_PATCH 1)
+
 
 find_package(Protobuf 2.6.1 REQUIRED)
 
@@ -60,3 +65,34 @@ target_include_directories(${PROJECT_NAME}
         ${CMAKE_CURRENT_BINARY_DIR}
 )
 target_link_libraries(${PROJECT_NAME} PUBLIC ${PROTOBUF_LIBRARY})
+
+
+# add a target to generate API documentation with Doxygen
+# Dependencies: Doxygen and proto2cpp.py
+FIND_PACKAGE(Doxygen)
+set(FILTER_PROTO2CPP_PY_PATH CACHE PATH "directory to the filter proto2cpp.py")
+
+if(NOT DOXYGEN_FOUND)
+
+    message(WARNING  "Doxygen could not be found.")
+
+else()
+	
+	if(NOT EXISTS ${FILTER_PROTO2CPP_PY_PATH}/proto2cpp.py)
+	
+	message(WARNING  "${FILTER_PROTO2CPP_PY_PATH}/proto2cpp.py could not be found.")
+
+	else()
+	
+		set(doxyfile_in ${CMAKE_CURRENT_SOURCE_DIR}/doxygen_config.cmake.in)
+		set(doxyfile ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+
+		configure_file(${doxyfile_in} ${doxyfile} @ONLY)
+
+		ADD_CUSTOM_TARGET(api_doc ALL 
+		COMMAND ${DOXYGEN_EXECUTABLE} ${doxyfile}
+		WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
+	
+	endif(NOT EXISTS ${FILTER_PROTO2CPP_PY_PATH}/proto2cpp.py)
+	
+endif(NOT DOXYGEN_FOUND)

README.md

@@ -3,9 +3,10 @@ Open Simulation Interface (OSI)
 
 [![Travis Build Status](https://travis-ci.org/OpenSimulationInterface/open-simulation-interface.svg?branch=master)](https://travis-ci.org/OpenSimulationInterface/open-simulation-interface)
 
+
 General description
 -------------------
-https://www.hot.ei.tum.de/forschung/automotive-veroeffentlichungen/
+[TUM Department of Electrical and Computer Engineering](https://www.hot.ei.tum.de/forschung/automotive-veroeffentlichungen/)
 
 
 Global remarks
@@ -38,13 +39,16 @@ Fault injection: how-to
 Injection of pre-defined sensor errors should be handled by a specialized "fault injector" component that acts like a
 sensor model component, i.e. it takes a SensorData message as input and returns a modified SensorData message as output.
 Specific errors should be handled as follows:
-- Ghost objects / false positive: An additional SensorDataObject is added to the list of objects in SensorData.object
-      with SensorDataObject.model_internal_object.ground_truth_type set to kTypeGhost.
-- False negative: The object is marked as not seen by the sensor by setting the property
-      SensorDataObject.model_internal_object.is_seen to false. The implementation of field-of-view calculation modules
-      should respect this flag and never reset an object marked as not-seen to seen.
+- Ghost objects / false positive:
+    An additional SensorDataObject is added to the list of objects in SensorData.object
+	with SensorDataObject.model_internal_object.ground_truth_type set to kTypeGhost.
+- False negative:
+    The object is marked as not seen by the sensor by setting the property 
+	SensorDataObject.model_internal_object.is_seen to false. The implementation 
+	of field-of-view calculation modules should respect this flag and never reset 
+	an object marked as not-seen to seen.
+
 
-	  
 Versioning
 ----------
 The version number is defined in InterfaceVersion::version_number in osi_common.proto as the field's default value.
@@ -70,9 +74,24 @@ The compatibility of both recorded files and code remains.
 - Changing or adding comments
 - Clarification of text passages explaining the message content
 
+
 Packaging
 ---------
 
 A specification to package sensor models using OSI as (extended)
 Functional Mock-up Units (FMUs) for use in simulation environments
 is available [here](https://github.com/OpenSimulationInterface/osi-sensor-model-packaging).
+
+
+Documentation
+-------------
+
+In order to generate the doxygen documentation for OSI, please follow the following steps: 
+1. Install [Doxygen](http://www.stack.nl/~dimitri/doxygen/download.html), set an environmental variable 'doxygen' with the path to the binary file and add it to the PATH variable: `PATH += %doxygen%`.
+2. Download the [vg-1.5.0.zip](https://github.com/vgteam/vg/releases/tag/v1.5.0). Unpack and copy the content of folder /vg-1.5.0/contrib/proto2cpp to your desired `<path-to-proto2cpp.py>`
+3. Install [graphviz-2.38](http://www.graphviz.org/Download_windows.php ), set an environmental variable 'graphviz' with the path to the binary file and add it to the PATH variable: `PATH += %graphviz%`.
+4. From the cmd navigate to the build directory and run: 
+```cmd
+cmake -DFILTER_PROTO2CPP_PY_PATH=<path-to-proto2cpp.py> <path-to-CMakeLists.txt>
+```
+5. The build process will then generate the doxygen documentation under the directory doc.

doxygen_config.cmake.in

@@ -0,0 +1,21 @@
+#set the name and version of the project according to the configuration in CMakeLists.txt
+PROJECT_NAME           = "@CMAKE_PROJECT_NAME@"
+PROJECT_NUMBER         = @VERSION_MAJOR@.@VERSION_MINOR@.@VERSION_PATCH@
+
+#Set input and output directories 
+INPUT                  = "@CMAKE_CURRENT_SOURCE_DIR@"
+INPUT       	      += "@CMAKE_CURRENT_SOURCE_DIR@/README.md"
+
+USE_MDFILE_AS_MAINPAGE = "@CMAKE_CURRENT_SOURCE_DIR@/README.md"
+
+OUTPUT_DIRECTORY       = "@CMAKE_CURRENT_SOURCE_DIR@/doc"
+IMAGE_PATH	       = "@CMAKE_CURRENT_SOURCE_DIR@/doc/images"
+
+# There is no standard configuration for .proto files documentation.
+# A Doxygen filter for .proto files has to be added under the directory doc/.
+JAVADOC_AUTOBRIEF      = NO
+EXTENSION_MAPPING      = proto=C
+FILE_PATTERNS          = *.proto
+INPUT_FILTER           = "python @FILTER_PROTO2CPP_PY_PATH@/proto2cpp.py"
+HAVE_DOT	       = YES
+