Adds documentation package

Author: epsilonrt

CMakeLists.txt

@@ -1,4 +1,4 @@
-# Copyright © 2018 Pascal JEAN, All rights reserved.
+# Copyright © 2018-2019 Pascal JEAN, All rights reserved.
 # This file is part of the libmodbuspp Project.
 #
 # The libmodbuspp Project is free software: you can redistribute it and/or modify
@@ -129,7 +129,7 @@ add_compile_options(-Wno-psabi)
 add_subdirectory (dev)
 add_subdirectory (lib)
 #add_subdirectory (utils)
-#add_subdirectory (doc)
+add_subdirectory (doc)
 
 if (MODBUSPP_WITH_DOXYGEN_DOC)
   add_dependencies(modbuspp-shared doc)

README.md

@@ -4,17 +4,44 @@ _A C++ wrapper for the [libmodbus](https://libmodbus.org/) library_
 
 ## Abstract
 
-libmodbus is a free software library to send/receive data according to the 
-Modbus protocol. This library is written in C and supports RTU (serial) and 
-TCP (Ethernet) communications.
-
-The libmodbuspp library provides a C++ overlay to [libmodbus](https://libmodbus.org/), a wrapper,
-having no other dependency than libmodbus and libstdc++
+[libmodbus](https://libmodbus.org/) is a free software library to send/receive 
+data according to the MODBUS protocol. This library is written in C and supports 
+RTU (serial) and TCP (Ethernet) communications.
+
+MODBUS is considered an application layer messaging protocol, providing 
+Master/Slave communication between devices connected together through buses or 
+networks. 
+On the OSI model, MODBUS is positioned at level 7. MODBUS is intended to be a 
+request/reply protocol and delivers services specified by function codes. 
+The function codes of MODBUS are elements of MODBUS’ request/reply PDUs 
+(Protocol Data Unit).
+
+In order to build the MODBUS application data unit, the client must initiate a 
+MODBUS transaction. It is the function which informs the server as to which type 
+of action to perform. The format of a request initiated by a Master is 
+established by the MODBUS application protocol. The function code field is then 
+coded into one byte. Only codes within the range of 1 through 255 are 
+considered valid, with 128-255 being reserved for exception responses. 
+When the Master sends a message to the Slave, it is the function code field 
+which informs the server of what type of action to perform.
+
+To define multiple actions, some functions will have sub-function codes added to 
+them. For instance, the Master is able to read the ON/OFF states of a group of 
+discreet outputs or inputs. 
+It could also read/write the data contents of a group of MODBUS registers. 
+When the Master receives the Slave response, the function code field is used by 
+the Slave to indicate either an error-free response or an exception response. 
+The Slave echoes to the request of the initial function code in the case of a 
+normal response.
+
+The libmodbuspp library provides a C++ overlay to 
+[libmodbus](https://libmodbus.org/), a wrapper, having no other dependency than 
+libmodbus and libstdc++
 
 A good example always better than a long explanation, this is an extremely 
 simple example:
 
-```c++
+```cpp
 uint16_t values[2]; // array to store the values of the input registers
 Master mb (Rtu, port, "19200E1"); // new master on RTU
 mb.open(); // open a connection
@@ -62,7 +89,7 @@ If you want to build from sources, you can follow the
 
 Here is a complete example that can be compiled without error:
 
-```c++
+```cpp
 #include <iostream>
 #include <string>
 #include <modbuspp.h>
@@ -105,11 +132,11 @@ in `main.cpp`
 
 To build, you must type the command:
 
-    $ g++ -o read-input-registers main.cpp $(pkg-config --cflags --libs libmodbuspp)
+    g++ -o read-input-registers main.cpp $(pkg-config --cflags --libs libmodbuspp)
 
 You can then run it :
 
-    $ ./read-input-registers 
+    ./read-input-registers 
     R0=9964
     R1=10029
 

dev/CMakeLists.txt

@@ -1,4 +1,4 @@
-# Copyright © 2018 Pascal JEAN, All rights reserved.
+# Copyright © 2018-2019 Pascal JEAN, All rights reserved.
 # This file is part of the libmodbuspp Project.
 #
 # The libmodbuspp Project is free software: you can redistribute it and/or modify

dev/cmake/GitVersion.cmake

@@ -1,4 +1,4 @@
-# Copyright © 2018 Pascal JEAN, All rights reserved.
+# Copyright © 2018-2019 Pascal JEAN, All rights reserved.
 # This file is part of the libmodbuspp Project.
 #
 # The libmodbuspp Project is free software: you can redistribute it and/or modify

doc/CMakeLists.txt

@@ -0,0 +1,80 @@
+# Copyright © 2018-2019 Pascal JEAN, All rights reserved.
+# This file is part of the libmodbuspp Project.
+#
+# The libmodbuspp Project is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# The libmodbuspp Project is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with the libmodbuspp Project.  If not, see <http://www.gnu.org/licenses/>.
+
+# doc CMakeLists.txt
+
+cmake_minimum_required(VERSION 2.8.11)
+
+set (MODBUSPP_WITH_DOXYGEN_DOC 0 CACHE BOOL "Enable build of the documentation")
+
+# set packaging dir
+if(NOT CPACK_PACKAGE_DIRECTORY)
+  set(CPACK_PACKAGE_DIRECTORY ${CMAKE_BINARY_DIR}/packages)
+endif()
+
+if("${CMAKE_PROJECT_NAME}" STREQUAL "Project")
+  set(PROJECT_SOURCE_DIR ${CMAKE_CURRENT_LIST_DIR}/..)
+endif()
+
+if (MODBUSPP_WITH_DOXYGEN_DOC)
+
+  find_package(Doxygen REQUIRED)
+  set(DOXYGEN_README ${PROJECT_SOURCE_DIR}/README.md)
+  set(DOXYGEN_FILE ${CMAKE_BINARY_DIR}/Doxyfile)
+  set(DOXYGEN_MAINPAGE ${CMAKE_BINARY_DIR}/main_page.dox)
+
+  set(DOXYGEN_INPUT_LIST 
+    ${PROJECT_SOURCE_DIR}/include/modbuspp.h
+    ${PROJECT_SOURCE_DIR}/include/modbuspp-data.h
+    )
+
+  set(DOXYGEN_INPUT "${CMAKE_BINARY_DIR}/main_page.dox")
+  foreach(item ${DOXYGEN_INPUT_LIST})
+    # get_filename_component(item_dir ${item} DIRECTORY)
+    string(APPEND DOXYGEN_INPUT " ${item} ")
+  endforeach(item ${DOXYGEN_INPUT_LIST})
+
+  #message("DOXYGEN_INPUT=${DOXYGEN_INPUT}")
+
+  configure_file(Doxyfile.in ${CMAKE_BINARY_DIR}/Doxyfile @ONLY)
+  configure_file(build_main_page.sh.in ${CMAKE_BINARY_DIR}/build_main_page.sh @ONLY)
+
+  add_custom_target(main_page.dox
+    COMMAND ${CMAKE_COMMAND} -E echo_append "Building API Documentation Main Page..."
+    COMMAND sh ${CMAKE_BINARY_DIR}/build_main_page.sh > /dev/null
+    COMMAND ${CMAKE_COMMAND} -E echo "Done."
+    DEPENDS main_page_header.dox main_page_footer.dox ${PROJECT_SOURCE_DIR}/README.md
+    )
+
+  add_custom_target(html
+    COMMAND ${CMAKE_COMMAND} -E echo_append "Building API Documentation..."
+    COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_FILE} > /dev/null
+    COMMAND ${CMAKE_COMMAND} -E echo "Done."
+    DEPENDS main_page.dox DoxygenLayout.xml Doxyfile.in ${DOXYGEN_INPUT_LIST}
+    )
+  
+  add_custom_target(doc)
+  add_dependencies(doc main_page.dox html)
+  
+  # message("MODBUSPP_INSTALL_DOC_DIR=${MODBUSPP_INSTALL_DOC_DIR}")
+  file(GLOB manpages  ${CMAKE_BINARY_DIR}/man/man3/Modbus_*.3)
+
+  install(DIRECTORY ${CMAKE_BINARY_DIR}/html/
+          DESTINATION ${MODBUSPP_INSTALL_DOC_DIR}/api-manual COMPONENT doc)
+  install(FILES ${manpages}
+          DESTINATION "${INSTALL_DATA_DIR}/man/man3" COMPONENT doc)
+
+endif(MODBUSPP_WITH_DOXYGEN_DOC)