Doc - fix documentation build script + a few other things (#5751)

Documentation/Books/AQL/Examples/MultiplePaths.md

@@ -4,7 +4,7 @@ Multiple Path Search
 The shortest path algorithm can only determine one shortest path.
 For example, if this is the full graph (based on the [mps_graph](../../Manual/Graphs/index.html#the-mps-graph)):
 
-![Example Graph](mps_graph.png)
+![Example Graph](../../Manual/Graphs/mps_graph.png)
 
 then a shortest path query from **A** to **C** may return the path `A -> B -> C` or `A -> D -> C`, but it's undefined which one (not taking edge weights into account here).
 

Documentation/Books/Cookbook/UseCases/CrawlingGithubPromises.md

@@ -84,7 +84,7 @@ The `promoteError` can be used for the github callback as well as the ArangoDB d
 
 ### Queues, Queues, Queues
 
-I've only needed a very simple job queue, so [queue-it][4] is a good choice.
+I've only needed a very simple job queue, so queue-it is a good choice.
 It provides a very simple API for handling job queues:
 
 ```
@@ -148,7 +148,7 @@ Therefore we need to pass the relevant data as parameters. It is not possible to
 
 ### Riding the Beast
 
-Start an ArangoDB instance (i.e. inside a [docker container][5]) and install the simple queue.
+Start an ArangoDB instance (i.e. inside a [docker container][4]) and install the simple queue.
 
 ```
 foxx-manager install queue-it /queue
@@ -185,7 +185,6 @@ be possible to avoid nodejs / ArangoDB roundtrips using more transactions.
 
 - [ArangoJS][1]
 - [npm promises][2]
-- [ArangoDB Foxx queue-it][4]
 
 The source code of this example is available from Github: <https://github.com/fceller/Foxxmender>
 
@@ -196,5 +195,4 @@ The source code of this example is available from Github: <https://github.com/fc
 [1]: https://github.com/arangodb/arangojs
 [2]: https://www.npmjs.com/package/promises
 [3]: https://github.com/fceller/Foxxmender
-[4]: https://github.com/arangodb/queue-it
-[5]: ../Cloud/DockerContainer.md
+[4]: ../Cloud/DockerContainer.md

Documentation/DocuBlocks/Rest/Administration/get_admin_server_mode.md

@@ -16,3 +16,4 @@ This is a public API so it does *not* require authentication.
 
 @RESTRETURNCODE{200}
 This API will return HTTP 200 if everything is ok
+@endDocuBlock

Documentation/Scripts/codeBlockReader.py

@@ -16,16 +16,16 @@ searchMDPaths = [
   "Drivers"
 ]
 searchPaths = [
-  "Documentation/Books/Manual/",
-  "Documentation/Books/AQL/",
-  "Documentation/Books/HTTP/",
-  "Documentation/Books/Cookbook/",
-  "Documentation/Books/Drivers/",
-  "Documentation/DocuBlocks/"
+  ["Documentation/Books/Manual/", False],
+  ["Documentation/Books/AQL/", False],
+  ["Documentation/Books/HTTP/", False],
+  ["Documentation/Books/Cookbook/", False],
+  ["Documentation/Books/Drivers/", False],
+  ["Documentation/DocuBlocks/", True]
 ]
 fullSuccess = True
 
-def file_content(filepath):
+def file_content(filepath, forceDokuBlockContent):
   """ Fetches and formats file's content to perform the required operation.
   """
 
@@ -36,9 +36,10 @@ def file_content(filepath):
   comment_indexes = []
   comments = []
   _start = None
-
+  docublockname = ""
   for line in enumerate(filelines):
     if "@startDocuBlock" in line[1]:
+      docublockname = line[1]
       # in the unprocessed md files we have non-terminated startDocuBlocks, else it is an error:
       if ((_start != None) and
           (not searchMDPaths[0] in filepath) and
@@ -47,16 +48,21 @@ def file_content(filepath):
           (not searchMDPaths[3] in filepath) and
           (not searchMDPaths[4] in filepath)):
         print "next startDocuBlock found without endDocuBlock in between in file %s [%s]" %(filepath, line)
-        raise
+        raise Exception
       _start = line[0]
     if "@endDocuBlock" in line[1]:
+      docublockname = ""
       try:
         _end = line[0] + 1
         comment_indexes.append([_start, _end])
         _start = None
       except NameError:
         print "endDocuBlock without previous startDocublock seen while analyzing file %s [%s]" %(filepath, line)
-        raise
+        raise Exception
+
+  if len(docublockname) != 0 and forceDokuBlockContent: 
+    print "no endDocuBlock found while analyzing file %s [%s]" %(filepath, docublockname)
+    raise Exception
 
   for index in comment_indexes:
     comments.append(filelines[index[0]: index[1]])
@@ -219,7 +225,7 @@ def example_content(filepath, fh, tag, blockType, placeIntoFilePath):
   fh.write(unicode("\n"))
 
 
-def fetch_comments(dirpath):
+def fetch_comments(dirpath, forceDokuBlockContent):
   """ Fetches comments from files and writes to a file in required format.
   """
   global fullSuccess
@@ -233,7 +239,7 @@ def fetch_comments(dirpath):
       if filename.endswith(validExtensions) and (filename.find("#") < 0):
 
         filepath = os.path.join(root, filename)
-        file_comments = file_content(filepath)
+        file_comments = file_content(filepath, forceDokuBlockContent)
         for comment in file_comments:
           fh.write(unicode("\n<!-- filename: %s -->\n" % filepath))
           for _com in comment:
@@ -289,9 +295,9 @@ if __name__ == "__main__":
   commentsFile.close()
   errorsFile.close()
   for i in searchPaths:
-    print "Searching for docublocks in " + i + ": "
-    dirpath = os.path.abspath(os.path.join(os.path.dirname( __file__ ), os.pardir,"ArangoDB/../../"+i))
-    fetch_comments(dirpath)
+    print "Searching for docublocks in " + i[0] + ": "
+    dirpath = os.path.abspath(os.path.join(os.path.dirname( __file__ ), os.pardir,"ArangoDB/../../"+i[0]))
+    fetch_comments(dirpath, i[1])
     os.path.abspath(os.path.join(os.path.dirname( __file__ ), '..', 'templates'))
-  if not fullSuccess: 
+  if not fullSuccess:
     sys.exit(1)

Documentation/Scripts/generateMdFiles.py

@@ -488,7 +488,7 @@ def walk_on_files(inDirPath, outDirPath):
                         skipped += 1
                         # print "Skipping %s -> %s" % (inFileFull, outFileFull)
                         continue;
-                print "%s -> %s" % (nextInFileFull, nextOutFileFull)
+                #print "%s -> %s" % (nextInFileFull, nextOutFileFull)
                 _mkdir_recursive(os.path.join(outDirPath, root))
                 findStartCode(nextInFileFull, nextOutFileFull, inDirPath)
     print STD_COLOR + "Processed %d files, skipped %d" % (count, skipped) + RESET