fix include of c files in documentation; improve handling of toc

doc/CMakeLists.txt

@@ -23,6 +23,13 @@ configure_file("${PROJECT_SOURCE_DIR}/doc/tutorial_server_firstSteps.rst"
 configure_file("${PROJECT_SOURCE_DIR}/doc/tutorial_client_firstSteps.rst"
                "${DOC_SRC_DIR}/tutorial_client_firstSteps.rst")
 
+# Copy example code
+set(EXAMPLES ${PROJECT_SOURCE_DIR}/examples/client_firstSteps.c
+             ${PROJECT_SOURCE_DIR}/examples/server_firstSteps.c
+             ${PROJECT_SOURCE_DIR}/examples/server_variable.c
+             ${PROJECT_SOURCE_DIR}/examples/server_method.c)
+file(COPY ${EXAMPLES} DESTINATION ${DOC_SRC_DIR})
+               
 function(generate_rst in out)
   add_custom_command(OUTPUT ${out} DEPENDS ${PROJECT_SOURCE_DIR}/tools/c2rst.py ${in}
                      PRE_BUILD COMMAND ${PYTHON_EXECUTABLE} ${PROJECT_SOURCE_DIR}/tools/c2rst.py ${in} ${out})

doc/conf.py

@@ -43,7 +43,7 @@ source_suffix = '.rst'
 #source_encoding = 'utf-8-sig'
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = 'toc'
 
 # General information about the project.
 project = u'open62541'

doc/index_html.rst

@@ -1,15 +0,0 @@
-.. include:: introduction.rst
-
-.. toctree::
-    :hidden:
-
-    self
-    building
-    tutorials
-    types
-    information_modelling
-    services
-    server
-    client
-    constants
-    internal

doc/internal.rst

@@ -1,8 +1,8 @@
 Internals
 =========
 
-.. include:: nodestore.rst
+.. toctree::
 
-.. include:: connection.rst
-
-.. include:: log.rst
+   nodestore
+   connection
+   log

doc/toc.rst

@@ -0,0 +1,15 @@
+open62541 Documentation
+#######################
+
+.. toctree::
+
+   index
+   building
+   tutorials
+   types
+   information_modelling
+   services
+   server
+   client
+   constants
+   internal

doc/tutorial_client_firstSteps.rst

@@ -5,41 +5,17 @@ You should already have a basic server from the previous tutorials. open62541
 provides both a server- and clientside API, so creating a client is as easy as
 creating a server. Copy the following into a file `myClient.c`:
 
-.. code-block:: c
-
-    #include "open62541.h"
-
-    int main(void) {
-      UA_Client *client = UA_Client_new(UA_ClientConfig_standard);
-      UA_StatusCode retval = UA_Client_connect(client, "opc.tcp://localhost:16664");
-      if(retval != UA_STATUSCODE_GOOD) {
-          UA_Client_delete(client);
-          return retval;
-      }
-
-      UA_Client_disconnect(client);
-      UA_Client_delete(client);
-      return 0;
-    }
+.. literalinclude:: client_firstSteps.c
+   :language: c
+   :linenos:
+   :lines: 4,5,12,14-
 
-Compilation is very much similar to the server example.
+Compilation is similar to the server example.
 
 .. code-block:: bash
 
    $ gcc -std=c99 open6251.c myClient.c -o myClient
 
-Reading a node attibute
-^^^^^^^^^^^^^^^^^^^^^^^
-
-In this example we are going to connect to the server from the second tutorial
-and read the value-attribute of the added variable node.
-
-.. literalinclude:: ${PROJECT_SOURCE_DIR}/examples/client_firstSteps.c
-   :language: c
-   :linenos:
-   :lines: 4,5,12,14-
-
-
 Further tasks
 ^^^^^^^^^^^^^
 * Try to connect to some other OPC UA server by changing

doc/tutorial_server_firstSteps.rst

@@ -17,7 +17,7 @@ have the ``open62541.c/.h`` files in the current folder.
 
 Now create a new C source-file called ``myServer.c`` with the following content:
 
-.. literalinclude:: ${PROJECT_SOURCE_DIR}/examples/server_firstSteps.c
+.. literalinclude:: server_firstSteps.c
    :language: c
    :linenos:
    :lines: 4,12,14-34

doc/tutorial_server_method.rst

@@ -16,7 +16,7 @@ The last example presents a way to bind a new method callback to an already
 instantiated method node.
 
 
-.. literalinclude:: ${PROJECT_SOURCE_DIR}/examples/server_method.c
+.. literalinclude:: server_method.c
    :language: c
    :linenos:
    :lines: 4,5,14,16-

doc/tutorial_server_variables.rst

@@ -10,7 +10,7 @@ connected to a physical process in the background.
 This is the code for a server with a single variable node holding an integer. We
 will take this example to explain some of the fundamental concepts of open62541.
 
-.. literalinclude:: ${PROJECT_SOURCE_DIR}/examples/server_variable.c
+.. literalinclude:: server_variable.c
    :language: c
    :linenos:
    :lines: 4,13,15-

doc/tutorials.rst

@@ -1,12 +1,10 @@
 Tutorials
 =========
 
-.. include:: tutorial_server_firstSteps.rst
+.. toctree::
 
-.. include:: tutorial_server_variables.rst
-
-.. include:: tutorial_server_method.rst
-
-.. include:: tutorial_noderelations.rst
-
-.. include:: tutorial_client_firstSteps.rst
+   tutorial_server_firstSteps.rst
+   tutorial_server_variables.rst
+   tutorial_server_method.rst
+   tutorial_noderelations.rst
+   tutorial_client_firstSteps.rst

examples/client_firstSteps.c

@@ -20,37 +20,25 @@ int main(void) {
         return (int)retval;
     }
 
-    //variables to store data
-    UA_DateTime raw_date = 0;
-    UA_String string_date;
+    /* Read the value attribute of the node. UA_Client_readValueAttribute is a
+     * wrapper for the raw read service available as UA_Client_Service_read. */
+    UA_Variant value; /* Variants can hold scalar values and arrays of any type */
+    UA_Variant_init(&value);
 
-    /* create a readrequest with one entry */
-    UA_ReadRequest rReq;
-    UA_ReadRequest_init(&rReq);
-    rReq.nodesToRead = UA_Array_new(1, &UA_TYPES[UA_TYPES_READVALUEID]);
-    rReq.nodesToReadSize = 1;
-
-    /* define the node and attribute to be read */
     #define NS0_CURRENT_TIME 2258
-    rReq.nodesToRead[0].nodeId = UA_NODEID_NUMERIC(0, NS0_CURRENT_TIME);
-    rReq.nodesToRead[0].attributeId = UA_ATTRIBUTEID_VALUE;
+    const UA_NodeId nodeId = UA_NODEID_NUMERIC(0, NS0_CURRENT_TIME);
 
-    /* call the service and print the result */
-    UA_ReadResponse rResp = UA_Client_Service_read(client, rReq);
-    if(rResp.responseHeader.serviceResult == UA_STATUSCODE_GOOD && rResp.resultsSize > 0 &&
-       rResp.results[0].hasValue && UA_Variant_isScalar(&rResp.results[0].value) &&
-       rResp.results[0].value.type == &UA_TYPES[UA_TYPES_DATETIME]) {
-        raw_date = *(UA_DateTime*)rResp.results[0].value.data;
-        printf("raw date is: %" PRId64 "\n", raw_date);
-        string_date = UA_DateTime_toString(raw_date);
+    retval = UA_Client_readValueAttribute(client, nodeId, &value);
+    if(retval == UA_STATUSCODE_GOOD && UA_Variant_isScalar(&value) &&
+       value.type == &UA_TYPES[UA_TYPES_DATETIME]) {
+        UA_DateTime raw_date = *(UA_DateTime*)value.data;
+        UA_String string_date = UA_DateTime_toString(raw_date);
         printf("string date is: %.*s\n", (int)string_date.length, string_date.data);
+        UA_String_deleteMembers(&string_date);
     }
 
-    UA_ReadRequest_deleteMembers(&rReq);
-    UA_ReadResponse_deleteMembers(&rResp);
-    UA_String_deleteMembers(&string_date);
-
-    UA_Client_disconnect(client);
-    UA_Client_delete(client);
-    return (int) UA_STATUSCODE_GOOD;
+    /* Clean up */
+    UA_Variant_deleteMembers(&value);
+    UA_Client_delete(client); /* Disconnects the client internally */
+    return UA_STATUSCODE_GOOD;
 }

include/ua_client.h

@@ -359,7 +359,10 @@ UA_Client_Service_publish(UA_Client *client, const UA_PublishRequest request) {
 
 #endif
 
-/** .. include:: client_highlevel.rst */
+/**
+ * .. toctree::
+ *
+ *    client_highlevel */
 
 #ifdef __cplusplus
 } // extern "C"

include/ua_types.h

@@ -835,7 +835,9 @@ UA_Guid UA_EXPORT UA_Guid_random(void);     /* no cryptographic entropy */
  *
  * The following data types were auto-generated from a definition in XML format.
  *
- * .. include:: types_generated.rst */
+ * .. toctree::
+ *
+ *    types_generated */
 #ifdef __cplusplus
 } // extern "C"
 #endif