From 4f4087a944cbf8a0a2b01f91787f1ef9fcaa07ce Mon Sep 17 00:00:00 2001 From: Wilfried Goesgens Date: Tue, 8 Dec 2015 23:45:36 +0100 Subject: [PATCH 1/3] Fix link to the error codes --- arangod/RestHandler/RestCursorHandler.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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} From 8f10c2b8a10950b5e1c27fe8657ed03a019e226a Mon Sep 17 00:00:00 2001 From: Wilfried Goesgens Date: Tue, 8 Dec 2015 23:47:18 +0100 Subject: [PATCH 2/3] Generate markdown from the restdescritpion instead of html. --- Documentation/Books/generateMdFiles.py | 40 +++++----- Documentation/Scripts/generateSwagger.py | 95 ++++++++++-------------- 2 files changed, 63 insertions(+), 72 deletions(-) diff --git a/Documentation/Books/generateMdFiles.py b/Documentation/Books/generateMdFiles.py index 508964d451..64be174dd7 100644 --- a/Documentation/Books/generateMdFiles.py +++ b/Documentation/Books/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 = "" + addText = unwrapPostJson( + getReference(thisVerb['parameters'][nParam]['schema'], route, verb),0) rc += addText return rc def getRestReplyBodyParam(param): - rc = "\n**Reply Body**\n\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 = "" + 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 = "" + 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! From 8d31426eb3451a522bfa1613ca80c2919875f377 Mon Sep 17 00:00:00 2001 From: Wilfried Goesgens Date: Wed, 9 Dec 2015 00:00:49 +0100 Subject: [PATCH 3/3] Move python scripts into the scripts directory --- Documentation/Books/Makefile | 12 +++--------- Documentation/{Books => Scripts}/codeBlockReader.py | 0 Documentation/{Books => Scripts}/deprecated.py | 0 Documentation/{Books => Scripts}/generateMdFiles.py | 0 4 files changed, 3 insertions(+), 9 deletions(-) rename Documentation/{Books => Scripts}/codeBlockReader.py (100%) rename Documentation/{Books => Scripts}/deprecated.py (100%) rename Documentation/{Books => Scripts}/generateMdFiles.py (100%) 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 100% rename from Documentation/Books/generateMdFiles.py rename to Documentation/Scripts/generateMdFiles.py