diff --git a/Documentation/Books/Makefile b/Documentation/Books/Makefile
index d7e0885b85..2ddec76eba 100644
--- a/Documentation/Books/Makefile
+++ b/Documentation/Books/Makefile
@@ -137,7 +137,7 @@ build-book:
echo cp $${WD}/$${pic} $${pic}; \
cp $${WD}/$${pic} $${pic}; \
done
- python generateMdFiles.py $(NAME) ppbooks/ ../../js/apps/system/_admin/aardvark/APP/api-docs.json $(FILTER)
+ python ../Scripts/generateMdFiles.py $(NAME) ppbooks/ ../../js/apps/system/_admin/aardvark/APP/api-docs.json $(FILTER)
cd ppbooks/$(NAME) && sed -i -e 's/VERSION_NUMBER/v$(newVersionNumber)/g' styles/header.js
cd ppbooks/$(NAME) && sed -i -e 's/VERSION_NUMBER/v$(newVersionNumber)/g' README.md
@@ -154,7 +154,7 @@ build-book:
cd ppbooks/$(NAME) && gitbook install
cd ppbooks/$(NAME) && gitbook build ./ ./../../books/$(NAME)
- python deprecated.py
+ python ../Scripts/deprecated.py
make book-check-markdown-leftovers
@@ -183,8 +183,6 @@ check-docublocks:
grep -v ppbook |\
grep -v allComments.txt |\
grep -v Makefile |\
- grep -v codeBlockReader.py |\
- grep -v generateMdFiles.py |\
grep -v '.*~:.*' |\
grep -v '.*#.*:.*' \
> /tmp/rawindoc.txt
@@ -192,8 +190,6 @@ check-docublocks:
grep -v ppbook |\
grep -v allComments.txt |\
grep -v Makefile |\
- grep -v codeBlockReader.py |\
- grep -v generateMdFiles.py |\
grep -v '.*~:.*' |\
grep -v '.*#.*:.*' \
>> /tmp/rawindoc.txt
@@ -204,8 +200,6 @@ check-docublocks:
grep -v ppbook |\
grep -v allComments.txt |\
grep -v Makefile |\
- grep -v codeBlockReader.py |\
- grep -v generateMdFiles.py |\
grep -v '.*~:.*' |\
grep -v '.*#.*:.*' \
>> /tmp/rawinprog.txt
@@ -248,7 +242,7 @@ clean: clean-intermediate
build-books-keep-md:
@test -d books || mkdir books
- python codeBlockReader.py
+ python ../Scripts/codeBlockReader.py
make build-book NAME=Users
build-books: clean-intermediate build-books-keep-md check-docublocks
diff --git a/Documentation/Books/codeBlockReader.py b/Documentation/Scripts/codeBlockReader.py
similarity index 100%
rename from Documentation/Books/codeBlockReader.py
rename to Documentation/Scripts/codeBlockReader.py
diff --git a/Documentation/Books/deprecated.py b/Documentation/Scripts/deprecated.py
similarity index 100%
rename from Documentation/Books/deprecated.py
rename to Documentation/Scripts/deprecated.py
diff --git a/Documentation/Books/generateMdFiles.py b/Documentation/Scripts/generateMdFiles.py
similarity index 94%
rename from Documentation/Books/generateMdFiles.py
rename to Documentation/Scripts/generateMdFiles.py
index 508964d451..64be174dd7 100644
--- a/Documentation/Books/generateMdFiles.py
+++ b/Documentation/Scripts/generateMdFiles.py
@@ -43,6 +43,16 @@ def getReference(name, source, verb):
raise Exception("invalid reference: " + ref + " in " + fn)
return ref
+removeDoubleLF = re.compile("\n\n")
+removeLF = re.compile("\n")
+
+def TrimThisParam(text, indent):
+ text = text.rstrip('\n').lstrip('\n')
+ text = removeDoubleLF.sub("\n", text)
+ if (indent > 0):
+ indent = (indent + 2) # align the text right of the list...
+ return removeLF.sub("\n" + ' ' * indent, text)
+
def unwrapPostJson(reference, layer):
global swagger
rc = ''
@@ -54,35 +64,29 @@ def unwrapPostJson(reference, layer):
if '$ref' in thisParam:
subStructRef = getReference(thisParam, reference, None)
- rc += "
" + param + ": "
- rc += swagger['definitions'][subStructRef]['description'] + ""
+ rc += ' ' * layer + " - **" + param + "**:\n"
rc += unwrapPostJson(subStructRef, layer + 1)
- rc += "
"
-
+
elif thisParam['type'] == 'object':
- rc += ' ' * layer + "" + param + ": " + brTrim(thisParam['description']) + ""
+ rc += ' ' * layer + " - **" + param + "**: " + TrimThisParam(brTrim(thisParam['description']), layer) + "\n"
elif swagger['definitions'][reference]['properties'][param]['type'] == 'array':
- rc += ' ' * layer + "" + param + ": " + brTrim(thisParam['description'])
+ rc += ' ' * layer + " - **" + param + "**: " + TrimThisParam(brTrim(thisParam['description']), layer)
if 'type' in thisParam['items']:
- rc += " of type " + thisParam['items']['type']#
+ rc += " of type " + thisParam['items']['type'] + "\n"
else:
if len(thisParam['items']) == 0:
- rc += "anonymous json object"
+ rc += "anonymous json object\n"
else:
try:
subStructRef = getReference(thisParam['items'], reference, None)
except:
print >>sys.stderr, "while analyzing: " + param
print >>sys.stderr, thisParam
- rc += "\n"
- rc += unwrapPostJson(subStructRef, layer + 1)
- rc += "
"
- rc += ''
+ rc += "\n" + unwrapPostJson(subStructRef, layer + 1)
else:
- rc += ' ' * layer + "" + param + ": " + thisParam['description'] + ''
+ rc += ' ' * layer + " - **" + param + "**: " + TrimThisParam(thisParam['description'], layer) + '\n'
return rc
-
def getRestBodyParam():
rc = "\n**Body Parameters**\n"
addText = ''
@@ -93,13 +97,13 @@ def getRestBodyParam():
if 'additionalProperties' in thisVerb['parameters'][nParam]['schema']:
addText = "free style json body"
else:
- addText = "" + unwrapPostJson(
- getReference(thisVerb['parameters'][nParam]['schema'], route, verb),0) + "
"
+ addText = unwrapPostJson(
+ getReference(thisVerb['parameters'][nParam]['schema'], route, verb),0)
rc += addText
return rc
def getRestReplyBodyParam(param):
- rc = "\n**Reply Body**\n"
+ rc = "\n**Reply Body**\n"
try:
rc += unwrapPostJson(getReference(thisVerb['responses'][param]['schema'], route, verb), 0)
@@ -107,7 +111,7 @@ def getRestReplyBodyParam(param):
print >>sys.stderr,"failed to search " + param + " in: "
print >>sys.stderr,json.dumps(thisVerb, indent=4, separators=(', ',': '), sort_keys=True)
raise
- return rc + "
\n"
+ return rc + "\n"
SIMPL_REPL_DICT = {
diff --git a/Documentation/Scripts/generateSwagger.py b/Documentation/Scripts/generateSwagger.py
index e84de71240..a838361e14 100755
--- a/Documentation/Scripts/generateSwagger.py
+++ b/Documentation/Scripts/generateSwagger.py
@@ -289,10 +289,10 @@ def Typography(txt):
txt = txt[0:-1]
# txt = BackTicks(txt)
- txt = AsteriskBold(txt)
- txt = AsteriskItalic(txt)
+# txt = AsteriskBold(txt)
+# txt = AsteriskItalic(txt)
# txt = FN(txt)
- txt = LIT(txt)
+# txt = LIT(txt)
# txt = FA(txt)
#
# no way to find out the correct link for Swagger,
@@ -487,32 +487,8 @@ def generic_handler_desc(cargo, r, message, op, para, name):
continue
line = Typography(line)
+ para[name] += line + '\n'
- if r.DESCRIPTION_LI.match(line):
- line = "" + line[2:]
- inLI = True
- elif inLI and r.DESCRIPTION_SP.match(line):
- line = line[2:]
- elif inLI and r.DESCRIPTION_BL.match(line):
- line = ""
- else:
- inLI = False
-
- if not inUL and inLI:
- line = " " + line
- inUL = True
- elif inUL and r.EMPTY_LINE.match(line):
- line = "
" + line
- inUL = False
-
- elif inLI and r.EMPTY_LINE.match(line):
- line = " " + line
- inUL = False
-
- if not inLI and r.EMPTY_LINE.match(line):
- line = "
"
-
- para[name] += line + ' '
para[name] = removeTrailingBR.sub("", para[name])
def start_docublock(cargo, r=Regexen()):
@@ -675,7 +651,7 @@ def restbodyparam(cargo, r=Regexen()):
if restBodyParam == None:
# https://github.com/swagger-api/swagger-ui/issues/1430
# once this is solved we can skip this:
- operation['description'] += "**A json post document with these Properties is required:**"
+ operation['description'] += "**A json post document with these Properties is required:**\n"
restBodyParam = {
'name': 'Json Post Body',
'x-description-offset': len(swagger['paths'][httpPath][method]['description']),
@@ -913,7 +889,7 @@ def restreplybody(cargo, r=Regexen()):
if restReplyBodyParam == None:
# https://github.com/swagger-api/swagger-ui/issues/1430
# once this is solved we can skip this:
- operation['description'] += "**A json document with these Properties is returned:**"
+ operation['description'] += "**A json document with these Properties is returned:**\n"
swagger['paths'][httpPath][method]['responses'][currentReturnCode][
'x-description-offset'] = len(swagger['paths'][httpPath][method]['description'])
swagger['paths'][httpPath][method]['responses'][currentReturnCode]['schema'] = {
@@ -1169,6 +1145,16 @@ def getReference(name, source, verb):
raise Exception("invalid reference: " + ref + " in " + fn)
return ref
+removeDoubleLF = re.compile("\n\n")
+removeLF = re.compile("\n")
+
+def TrimThisParam(text, indent):
+ text = text.rstrip('\n').lstrip('\n')
+ text = removeDoubleLF.sub("\n", text)
+ if (indent > 0):
+ indent = (indent + 2) # align the text right of the list...
+ return removeLF.sub("\n" + ' ' * indent, text)
+
def unwrapPostJson(reference, layer):
global swagger
rc = ''
@@ -1180,32 +1166,27 @@ def unwrapPostJson(reference, layer):
if '$ref' in thisParam:
subStructRef = getReference(thisParam, reference, None)
- rc += "" + param + ": "
- rc += swagger['definitions'][subStructRef]['description'] + ""
+ rc += ' ' * layer + " - **" + param + "**:\n"
rc += unwrapPostJson(subStructRef, layer + 1)
- rc += "
"
-
+
elif thisParam['type'] == 'object':
- rc += ' ' * layer + "" + param + ": " + brTrim(thisParam['description']) + ""
+ rc += ' ' * layer + " - **" + param + "**: " + TrimThisParam(brTrim(thisParam['description']), layer) + "\n"
elif swagger['definitions'][reference]['properties'][param]['type'] == 'array':
- rc += ' ' * layer + "" + param + ": " + brTrim(thisParam['description'])
+ rc += ' ' * layer + " - **" + param + "**: " + TrimThisParam(brTrim(thisParam['description']), layer)
if 'type' in thisParam['items']:
- rc += " of type " + thisParam['items']['type']#
+ rc += " of type " + thisParam['items']['type'] + "\n"
else:
if len(thisParam['items']) == 0:
- rc += "anonymous json object"
+ rc += "anonymous json object\n"
else:
try:
subStructRef = getReference(thisParam['items'], reference, None)
except:
print >>sys.stderr, "while analyzing: " + param
print >>sys.stderr, thisParam
- rc += "\n"
- rc += unwrapPostJson(subStructRef, layer + 1)
- rc += "
"
- rc += ''
+ rc += "\n" + unwrapPostJson(subStructRef, layer + 1)
else:
- rc += ' ' * layer + "" + param + ": " + thisParam['description'] + ''
+ rc += ' ' * layer + " - **" + param + "**: " + TrimThisParam(thisParam['description'], layer) + '\n'
return rc
@@ -1299,12 +1280,14 @@ for route in swagger['paths'].keys():
if thisVerb['parameters'][nParam]['in'] == 'body':
descOffset = thisVerb['parameters'][nParam]['x-description-offset']
addText = ''
- postText = thisVerb['description'][:descOffset]
+ postText = ''
+ paramDesc = thisVerb['description'][:descOffset]
+ if len(paramDesc) > 0:
+ postText += paramDesc
if 'additionalProperties' in thisVerb['parameters'][nParam]['schema']:
- addText = "free style json body"
+ addText = "\nfree style json body\n\n"
else:
- addText = "" + unwrapPostJson(
- getReference(thisVerb['parameters'][nParam]['schema'], route, verb),0) + "
"
+ addText = "\n" + unwrapPostJson(getReference(thisVerb['parameters'][nParam]['schema'], route, verb),1) + "\n\n"
postText += addText
postText += thisVerb['description'][descOffset:]
@@ -1315,30 +1298,34 @@ for route in swagger['paths'].keys():
if 'responses' in thisVerb:
for nRC in thisVerb['responses']:
if 'x-description-offset' in thisVerb['responses'][nRC]:
-
descOffset = thisVerb['responses'][nRC]['x-description-offset']
#print descOffset
#print offsetPlus
descOffset += offsetPlus
- addText = ''
+ addText = '\n##HTTP ' + nRC
#print thisVerb['responses'][nRC]['description']
postText = thisVerb['description'][:descOffset]
#print postText
+ replyDescription = TrimThisParam(thisVerb['responses'][nRC]['description'], 0)
+ if (len(replyDescription) > 0):
+ addText += '\n' + replyDescription + '\n'
if 'additionalProperties' in thisVerb['responses'][nRC]['schema']:
- addText = "free style json body"
+ addText += "\n free style json body\n"
else:
- addText = "" + unwrapPostJson(
- getReference(thisVerb['responses'][nRC]['schema'], route, verb),0) + "
"
+ addText += "\n" + unwrapPostJson(
+ getReference(thisVerb['responses'][nRC]['schema'], route, verb),0) + '\n'
#print addText
postText += addText
- postText += thisVerb['responses'][nRC]['description'][descOffset:]
+ postText += thisVerb['description'][descOffset:]
offsetPlus += len(addText)
thisVerb['description'] = postText
+ #print '-'*80
+ #print thisVerb['description']
# Append the examples to the description:
if 'x-examples' in thisVerb and len(thisVerb['x-examples']) > 0:
- thisVerb['description'] += '
'
+ thisVerb['description'] += '\n'
for nExample in range(0, len(thisVerb['x-examples'])):
thisVerb['description'] += thisVerb['x-examples'][nExample]
thisVerb['x-examples'] = []# todo unset!
diff --git a/arangod/RestHandler/RestCursorHandler.cpp b/arangod/RestHandler/RestCursorHandler.cpp
index 1ed3acc600..a961d34100 100644
--- a/arangod/RestHandler/RestCursorHandler.cpp
+++ b/arangod/RestHandler/RestCursorHandler.cpp
@@ -515,7 +515,7 @@ triagens::basics::Json RestCursorHandler::buildExtra (triagens::aql::QueryResult
/// error occurs during query processing, the server will respond with *HTTP 400*.
/// Again, the body of the response will contain details about the error.
///
-/// A list of query errors can be found (../ArangoErrors/README.md) here.
+/// A [list of query errors can be found here](../ErrorCodes/README.md).
///
///
/// @RESTRETURNCODE{404}