From 5dfc98491310bade550385808905cbd1c6169c4d Mon Sep 17 00:00:00 2001 From: Felix Krause Date: Wed, 21 Sep 2016 21:20:57 +0200 Subject: [PATCH] Updated documentation for new structure --- config.nims | 2 ++ doc/style.css | 33 ++++++++++++++++++++++++++++++ nimdoc.cfg | 18 +++++++++++++++-- yaml.nim | 46 ++++++++++++++++++++++++++++++++---------- yaml/common.nim | 7 +++++++ yaml/dom.nim | 14 ++++++++++++- yaml/hints.nim | 8 +++++++- yaml/parser.nim | 9 ++++++++- yaml/presenter.nim | 8 +++++++- yaml/serialization.nim | 14 ++++++++++++- yaml/stream.nim | 10 ++++++++- yaml/taglib.nim | 10 ++++++++- yaml/tojson.nim | 9 ++++++++- 13 files changed, 167 insertions(+), 21 deletions(-) diff --git a/config.nims b/config.nims index c87da1c..36e6f50 100644 --- a/config.nims +++ b/config.nims @@ -21,6 +21,8 @@ task serializationTests, "Run serialization tests": task documentation, "Generate documentation": exec "mkdir -p docout" exec r"nim doc2 -o:docout/yaml.html --docSeeSrcUrl:https://github.com/flyx/NimYAML/blob/`git log -n 1 --format=%H` yaml" + # bash! ah-ah \\ savior of the universe + exec r"find yaml -type f -print0 | while read -d '' -r f; do a=${f#yaml/}; nim doc2 -o:docout/yaml.${a%%.nim}.html --docSeeSrcUrl:https://github.com/flyx/NimYAML/blob/yaml/`git log -n 1 --format=%H` $f; done" exec r"nim rst2html -o:docout/index.html doc/index.txt" exec r"nim rst2html -o:docout/api.html doc/api.txt" exec r"nim rst2html -o:docout/serialization.html doc/serialization.txt" diff --git a/doc/style.css b/doc/style.css index 2b93efb..3be9e52 100644 --- a/doc/style.css +++ b/doc/style.css @@ -18,6 +18,11 @@ header a { padding-right: 5px; } +header a.active { + background: #877 !important; + color: black !important; +} + header span { display: inline-block; line-height: 50px; @@ -27,6 +32,34 @@ header span { padding-right: 5px; } +header span a { + display: block; +} + +header span ul { + display: none; + position: absolute; + top: 100%; + list-style: none; + background: #111; + margin: 0; +} + +header span ul:after { + content: ""; clear: both; display: block; +} + +header span:hover > ul { + display: block; +} + +header span ul a { + font-size: smaller; + font-family: "Source Code Pro", Menlo, "Courier New", Courier, monospace; + padding: 0 10px; + line-height: 40px; +} + header a:link, header a:visited { background: inherit; diff --git a/nimdoc.cfg b/nimdoc.cfg index acc34d7..1368b06 100644 --- a/nimdoc.cfg +++ b/nimdoc.cfg @@ -98,7 +98,7 @@ doc.file = """ - + @@ -111,7 +111,21 @@ doc.file = """ Docs: Overview Serialization - Module yaml + + Modules + +
diff --git a/yaml.nim b/yaml.nim index ffa5f0c..43102fb 100644 --- a/yaml.nim +++ b/yaml.nim @@ -1,20 +1,44 @@ # NimYAML - YAML implementation in Nim -# (c) Copyright 2015 Felix Krause +# (c) Copyright 2016 Felix Krause # # See the file "copying.txt", included in this # distribution, for details about the copyright. -## This module provides facilities to generate and interpret -## `YAML `_ character streams. All primitive operations on -## data objects use a `YamlStream <#YamlStream>`_ either as source or as -## output. Because this stream is implemented as iterator, it is possible to -## process YAML input and output sequentially, i.e. without loading the -## processed data structure completely into RAM. This supports the processing of -## large data structures. +## This is the parent module of NimYAML, a package that provides facilities to +## generate and interpret `YAML `_ character streams. Importing +## this package will import everything from all subpackages. ## -## As YAML is a strict superset of `JSON `_, JSON input is -## automatically supported. While JSON is less readable than YAML, -## this enhances interoperability with other languages. +## There are three high-level APIs which are probably most useful: +## +## * The serialization API in `serialization `_ enables +## you to load YAML data directly into native Nim types, and reversely dump +## native Nim types as YAML. +## * The DOM API in `dom `_ parses YAML files in a tree structure +## which you can navigate. +## * The JSON API in `tojson `_ parses YAML files into the +## Nim stdlib's JSON structure, which may be useful if you have other modules +## which expect JSON input. Note that the serialization API is able to write +## and load JSON; you do not need the JSON API for that. +## +## Apart from those high-level APIs, NimYAML implements a low-level API which +## enables you to process YAML input as data stream which does not need to be +## loaded into RAM completely at once. It consists of the following modules: +## +## * The stream API in `stream `_ defines the central type for +## stream processing, ``YamlStream``. It also contains definitions and +## constructor procs for stream events. +## * The parser API in `parser `_ gives you direct access to +## the YAML parser's output. +## * The presenter API in `presenter `_ gives you direct +## access to the presenter, i.e. the module that renders a YAML character +## stream. +## * The taglib API in `taglib `_ provides a data structure +## for keeping track of YAML tags that are generated by the parser or used in +## the presenter. +## * The hints API in `hints `_ provides a simple proc for +## guessing the type of a scalar value. +## * Finally, some basic types have been placed in `common `_ +## because of dependencies between the modules. import yaml.common, yaml.dom, yaml.hints, yaml.parser, yaml.presenter, yaml.serialization, yaml.stream, yaml.taglib, yaml.tojson diff --git a/yaml/common.nim b/yaml/common.nim index f0bbeee..d3ab734 100644 --- a/yaml/common.nim +++ b/yaml/common.nim @@ -4,6 +4,13 @@ # See the file "copying.txt", included in this # distribution, for details about the copyright. +## ================== +## Module yaml.common +## ================== +## +## This module hosts some types which could not be placed in other modules +## because of inter-module dependencies. + import hashes type diff --git a/yaml/dom.nim b/yaml/dom.nim index 83a57fa..075e4b7 100644 --- a/yaml/dom.nim +++ b/yaml/dom.nim @@ -1,9 +1,21 @@ # NimYAML - YAML implementation in Nim -# (c) Copyright 2015 Felix Krause +# (c) Copyright 2016 Felix Krause # # See the file "copying.txt", included in this # distribution, for details about the copyright. +## =============== +## Module yaml.dom +## =============== +## +## This is the DOM API, which enables you to load YAML into a tree-like +## structure. It can also dump the structure back to YAML. Formally, it +## represents the *Representation Graph* as defined in the YAML specification. +## +## The main interface of this API are ``loadDOM`` and ``dumpDOM``. The other +## exposed procs are low-level and useful if you want to load or generate parts +## of a ``YamlStream``. + import tables, streams import common, stream, taglib, serialization, ../private/internal, parser, presenter diff --git a/yaml/hints.nim b/yaml/hints.nim index 6359cf4..0892787 100644 --- a/yaml/hints.nim +++ b/yaml/hints.nim @@ -1,9 +1,15 @@ # NimYAML - YAML implementation in Nim -# (c) Copyright 2015 Felix Krause +# (c) Copyright 2016 Felix Krause # # See the file "copying.txt", included in this # distribution, for details about the copyright. +## ================= +## Module yaml.hints +## ================= +## +## The hints API enables you to guess the type of YAML scalars. + import macros import ../private/internal diff --git a/yaml/parser.nim b/yaml/parser.nim index fa66e3e..e882d66 100644 --- a/yaml/parser.nim +++ b/yaml/parser.nim @@ -1,9 +1,16 @@ # NimYAML - YAML implementation in Nim -# (c) Copyright 2015 Felix Krause +# (c) Copyright 2016 Felix Krause # # See the file "copying.txt", included in this # distribution, for details about the copyright. +## ================== +## Module yaml.parser +## ================== +## +## This is the low-level parser API. A ``YamlParser`` enables you to parse any +## non-nil string or Stream object as YAML character stream. + import tables, strutils, macros, streams import common, taglib, stream, ../private/lex, ../private/internal diff --git a/yaml/presenter.nim b/yaml/presenter.nim index ec84568..05044bf 100644 --- a/yaml/presenter.nim +++ b/yaml/presenter.nim @@ -1,9 +1,15 @@ # NimYAML - YAML implementation in Nim -# (c) Copyright 2015 Felix Krause +# (c) Copyright 2016 Felix Krause # # See the file "copying.txt", included in this # distribution, for details about the copyright. +## ===================== +## Module yaml.presenter +## ===================== +## +## This is the presenter API, used for generating YAML character streams. + import streams, queues, strutils import common, taglib, stream, ../private/internal, hints, parser, stream diff --git a/yaml/serialization.nim b/yaml/serialization.nim index 53009e2..ea4ad77 100644 --- a/yaml/serialization.nim +++ b/yaml/serialization.nim @@ -1,9 +1,21 @@ # NimYAML - YAML implementation in Nim -# (c) Copyright 2015 Felix Krause +# (c) Copyright 2016 Felix Krause # # See the file "copying.txt", included in this # distribution, for details about the copyright. +## ========================= +## Module yaml.serialization +## ========================= +## +## This is the most high-level API of NimYAML. It enables you to parse YAML +## character streams directly into native YAML types and vice versa. It builds +## on top of the low-level parser and presenter APIs. +## +## It is possible to define custom construction and serialization procs for any +## type. Please consult the serialization guide on the NimYAML website for more +## information. + import tables, typetraits, strutils, macros, streams import parser, common, taglib, presenter, stream, ../private/internal, hints diff --git a/yaml/stream.nim b/yaml/stream.nim index bc9ed26..48282b5 100644 --- a/yaml/stream.nim +++ b/yaml/stream.nim @@ -1,9 +1,17 @@ # NimYAML - YAML implementation in Nim -# (c) Copyright 2015 Felix Krause +# (c) Copyright 2016 Felix Krause # # See the file "copying.txt", included in this # distribution, for details about the copyright. +## ================== +## Module yaml.stream +## ================== +## +## The stream API provides the basic data structure on which all low-level APIs +## operate. It is not named ``streams`` to not confuse it with the modle in the +## stdlib with that name. + import common, ../private/internal import taglib diff --git a/yaml/taglib.nim b/yaml/taglib.nim index d722e90..63f9512 100644 --- a/yaml/taglib.nim +++ b/yaml/taglib.nim @@ -1,9 +1,17 @@ # NimYAML - YAML implementation in Nim -# (c) Copyright 2015 Felix Krause +# (c) Copyright 2016 Felix Krause # # See the file "copying.txt", included in this # distribution, for details about the copyright. +## ================== +## Module yaml.taglib +## ================== +## +## The taglib API enables you to query real names of tags emitted by the parser +## and create own tags. It also enables you to define tags for types used with +## the serialization API. + import tables, macros import common diff --git a/yaml/tojson.nim b/yaml/tojson.nim index e29427a..f39e3e1 100644 --- a/yaml/tojson.nim +++ b/yaml/tojson.nim @@ -1,9 +1,16 @@ # NimYAML - YAML implementation in Nim -# (c) Copyright 2015 Felix Krause +# (c) Copyright 2016 Felix Krause # # See the file "copying.txt", included in this # distribution, for details about the copyright. +## ================== +## Module yaml.tojson +## ================== +## +## The tojson API enables you to parser a YAML character stream into the JSON +## structures provided by Nim's stdlib. + import json, streams, strutils, tables import common, taglib, hints, serialization, stream, ../private/internal, parser