From b7828884bd43a044fa8329f27459459547be9ca3 Mon Sep 17 00:00:00 2001 From: Felix Krause Date: Sun, 24 Jan 2016 19:15:50 +0100 Subject: [PATCH] Documentation fixes. * Some typo fixes in code * nim documentation now generates API doc with source links * presenter now uses "" if a string starts with @ or ` * Removed some outdated stuff --- config.nims | 9 ++------- doc/style.css | 9 +++++++++ private/fastparse.nim | 46 +++++++++++++++++++++---------------------- private/presenter.nim | 2 +- yaml.nim | 11 +++-------- 5 files changed, 38 insertions(+), 39 deletions(-) diff --git a/config.nims b/config.nims index 4038bd1..a0943b5 100644 --- a/config.nims +++ b/config.nims @@ -8,11 +8,6 @@ task tests, "Run all tests": --verbosity:0 setCommand "c", "test/tests" -task lexerTests, "Run lexer tests": - --r - --verbosity:0 - setCommand "c", "test/lexing" - task parserTests, "Run parser tests": --r --verbosity:0 @@ -25,8 +20,8 @@ task serializationTests, "Run serialization tests": task documentation, "Generate documentation": exec "mkdir -p docout" - exec r"nim doc2 -o:docout/yaml.html yaml" - exec r"nim doc2 -o:docout/serialization.html yaml/serialization.nim" + exec r"nim doc2 -o:docout/yaml.html --docSeeSrcUrl:https://github.com/flyx/NimYAML/blob/`git log -n 1 --format=%H` yaml" + exec r"nim doc2 -o:docout/serialization.html --docSeeSrcUrl:https://github.com/flyx/NimYAML/blob/`git log -n 1 --format=%H` yaml/serialization.nim" exec r"nim rst2html -o:docout/index.html doc/index.txt" exec "cp doc/docutils.css doc/style.css doc/testing.html docout" setCommand "nop" diff --git a/doc/style.css b/doc/style.css index 32983f6..1f91216 100644 --- a/doc/style.css +++ b/doc/style.css @@ -66,6 +66,15 @@ html { background-color: rgba(252, 248, 244, 0.75); } +/* necessary for links to scroll to the right position */ +dt:before { + margin-top: -50px; + height: 50px; + content: ' '; + display: block; + visibility: hidden; +} + #testingground textarea { width: 100%; height: 100%; diff --git a/private/fastparse.nim b/private/fastparse.nim index 3f8d059..3a0fbf5 100644 --- a/private/fastparse.nim +++ b/private/fastparse.nim @@ -136,7 +136,7 @@ template handleObjectStart(k: YamlStreamEventKind) {.dirty.} = debug("started sequence at " & (if level.indentation == -1: $indentation else: $level.indentation)) level.kind = fplSequence - tag = yTagQuestionmark + tag = yTagQuestionMark anchor = yAnchorNone if level.indentation == -1: level.indentation = indentation @@ -183,7 +183,7 @@ template handleMapKeyIndicator() {.dirty.} = of fplMapValue: if level.indentation != indentation: parserError("Invalid indentation of map key indicator") - yield scalarEvent("", yTagQuestionmark, yAnchorNone) + yield scalarEvent("", yTagQuestionMark, yAnchorNone) level.kind = fplMapKey ancestry.add(level) level = FastParseLevel(kind: fplUnknown, indentation: -1) @@ -205,16 +205,16 @@ template handleMapValueIndicator() {.dirty.} = of fplUnknown: if level.indentation == -1: handleObjectStart(yamlStartMap) - yield scalarEvent("", yTagQuestionmark, yAnchorNone) + yield scalarEvent("", yTagQuestionMark, yAnchorNone) else: yield scalarEvent("", tag, anchor) - tag = yTagQuestionmark + tag = yTagQuestionMark anchor = yAnchorNone ancestry[ancestry.high].kind = fplMapValue of fplMapKey: if level.indentation != indentation: parserError("Invalid indentation of map key indicator") - yield scalarEvent("", yTagQuestionmark, yAnchorNone) + yield scalarEvent("", yTagQuestionMark, yAnchorNone) level.kind = fplMapValue ancestry.add(level) level = FastParseLevel(kind: fplUnknown, indentation: -1) @@ -238,14 +238,14 @@ template initDocValues() {.dirty.} = shorthands["!!"] = "tag:yaml.org,2002:" nextAnchorId = 0.AnchorId level = FastParseLevel(kind: fplUnknown, indentation: -1) - tag = yTagQuestionmark + tag = yTagQuestionMark anchor = yAnchorNone template handleTagHandle() {.dirty.} = startToken() if level.kind != fplUnknown: parserError("Unexpected tag handle") - if tag != yTagQuestionmark: + if tag != yTagQuestionMark: parserError("Only one tag handle is allowed per node") content = "" var @@ -281,7 +281,7 @@ template handleAlias() {.dirty.} = startToken() if level.kind != fplUnknown: parserError("Unexpected token") - if anchor != yAnchorNone or tag != yTagQuestionmark: + if anchor != yAnchorNone or tag != yTagQuestionMark: parserError("Alias may not have anchor or tag") content = "" p.lexer.anchorName(content) @@ -338,7 +338,7 @@ template handleBlockItemStart() {.dirty.} = level = FastParseLevel(kind: fplUnknown, indentation: indentation) of fplMapValue: yield scalarEvent("", tag, anchor) - tag = yTagQuestionmark + tag = yTagQuestionMark anchor = yAnchorNone level.kind = fplMapKey ancestry.add(level) @@ -1313,8 +1313,8 @@ proc parse*(p: YamlParser, s: Stream): YamlStream = var stateAfter: FastParseState content = "" p.lexer.blockScalar(content, stateAfter) - if tag == yTagQuestionmark: - tag = yTagExclamationmark + if tag == yTagQuestionMark: + tag = yTagExclamationMark yield scalarEvent(content, tag, anchor) handleObjectEnd(stateAfter) of '-': @@ -1424,14 +1424,14 @@ proc parse*(p: YamlParser, s: Stream): YamlStream = case level.kind of fplMapValue: yield scalarEvent("", tag, anchor) - tag = yTagQuestionmark + tag = yTagQuestionMark anchor = yAnchorNone level.kind = fplMapKey of fplMapKey: - if tag != yTagQuestionmark or anchor != yAnchorNone or + if tag != yTagQuestionMark or anchor != yAnchorNone or explicitFlowKey: yield scalarEvent("", tag, anchor) - tag = yTagQuestionmark + tag = yTagQuestionMark anchor = yAnchorNone yield scalarEvent("", tag, anchor) of fplSequence: @@ -1446,9 +1446,9 @@ proc parse*(p: YamlParser, s: Stream): YamlStream = level = ancestry.pop() case level.kind of fplSequence: - if tag != yTagQuestionmark or anchor != yAnchorNone: + if tag != yTagQuestionMark or anchor != yAnchorNone: yield scalarEvent("", tag, anchor) - tag = yTagQuestionmark + tag = yTagQuestionMark anchor = yAnchorNone of fplMapKey, fplMapValue: startToken() @@ -1463,17 +1463,17 @@ proc parse*(p: YamlParser, s: Stream): YamlStream = case level.kind of fplSequence: yield scalarEvent("", tag, anchor) - tag = yTagQuestionmark + tag = yTagQuestionMark anchor = yAnchorNone of fplMapValue: yield scalarEvent("", tag, anchor) - tag = yTagQuestionmark + tag = yTagQuestionMark anchor = yAnchorNone level.kind = fplMapKey explicitFlowKey = false of fplMapKey: yield scalarEvent("", tag, anchor) - tag = yTagQuestionmark + tag = yTagQuestionMark anchor = yAnchorNone yield scalarEvent("", tag, anchor) explicitFlowKey = false @@ -1492,7 +1492,7 @@ proc parse*(p: YamlParser, s: Stream): YamlStream = parserError("Unexpected token (expected ',')") of fplMapKey: yield scalarEvent("", tag, anchor) - tag = yTagQuestionmark + tag = yTagQuestionMark anchor = yAnchorNone level.kind = fplMapValue of fplUnknown, fplScalar: @@ -1514,8 +1514,8 @@ proc parse*(p: YamlParser, s: Stream): YamlStream = content = "" startToken() p.lexer.doubleQuotedScalar(content) - if tag == yTagQuestionmark: - tag = yTagExclamationmark + if tag == yTagQuestionMark: + tag = yTagExclamationMark yield scalarEvent(content, tag, anchor) handleObjectEnd(fpFlowAfterObject) of '!': @@ -1567,7 +1567,7 @@ proc parse*(p: YamlParser, s: Stream): YamlStream = of fplSequence: discard of fplMapValue: - yield scalarEvent("", yTagQuestionmark, yAnchorNone) + yield scalarEvent("", yTagQuestionMark, yAnchorNone) level.kind = fplMapKey explicitFlowKey = false of fplMapKey: diff --git a/private/presenter.nim b/private/presenter.nim index 51d4351..24d6792 100644 --- a/private/presenter.nim +++ b/private/presenter.nim @@ -12,7 +12,7 @@ type dFlowSequenceStart proc needsEscaping(scalar: string): bool {.raises: [].} = - scalar.len == 0 or + scalar.len == 0 or scalar[0] in ['@', '`'] or scalar.find({'{', '}', '[', ']', ',', '#', '-', ':', '?', '%', '"', '\'', '\x0A', '\c'}) != -1 diff --git a/yaml.nim b/yaml.nim index 3a2b37b..1d74d1c 100644 --- a/yaml.nim +++ b/yaml.nim @@ -27,7 +27,7 @@ type TypeHint* = enum ## A type hint can be computed from scalar content and tells you what ## NimYAML thinks the scalar's type is. It is generated by - ## `guessType <#guessType,string,TypeHint>`_ The first matching RegEx + ## `guessType <#guessType,string>`_ The first matching RegEx ## in the following table will be the type hint of a scalar string. ## ## You can use it to determine the type of YAML scalars that have a '?' @@ -118,14 +118,9 @@ type TagLibrary* = ref object ## A ``TagLibrary`` maps tag URIs to ``TagId`` s. ## - ## Three tag libraries are provided with this module: - ## `failsafeTagLibrary <#failsafeTagLibrary>`_, - ## `coreTagLibrary <#coreTagLibrary>`_, and - ## `extendedTagLibrary <#extendedTagLibrary>`_. - ## ## When `YamlParser <#YamlParser>`_ encounters tags not existing in the ## tag library, it will use - ## `registerTagUri <#registerTagUri,TagLibrary,string,TagId>`_ to add + ## `registerTagUri <#registerTagUri,TagLibrary,string>`_ to add ## the tag to the library. ## ## You can base your tag library on common tag libraries by initializing @@ -148,7 +143,7 @@ type YamlParser* = ref object ## A parser object. Retains its ``TagLibrary`` across calls to - ## `parse <#parse,YamlParser,Stream,YamlStream>`_. Can be used + ## `parse <#parse,YamlParser,Stream>`_. Can be used ## to access anchor names while parsing a YAML character stream, but ## only until the document goes out of scope (i.e. until ## ``yamlEndDocument`` is yielded).