Updated documentation for new structure

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"

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;

nimdoc.cfg

@@ -111,7 +111,21 @@ doc.file = """
   <span>Docs:</span>
   <a href="api.html">Overview</a>
   <a href="serialization.html">Serialization</a>
-  <a href="yaml.html">Module yaml</a>
+  <span>
+    <a href="#">Modules</a>
+    <ul>
+      <li><a href="yaml.html">yaml</a></li>
+      <li><a href="yaml.common.html">yaml.common</a></li>
+      <li><a href="yaml.dom.html">yaml.dom</a></li>
+      <li><a href="yaml.hints.html">yaml.hints</a></li>
+      <li><a href="yaml.parser.html">yaml.parser</a></li>
+      <li><a href="yaml.presenter.html">yaml.presenter</a></li>
+      <li><a href="yaml.serialization.html">yaml.serialization</a></li>
+      <li><a href="yaml.stream.html">yaml.stream</a></li>
+      <li><a href="yaml.taglib.html">yaml.taglib</a></li>
+      <li><a href="yaml.tojson.html">yaml.tojson</a></li>
+    </ul>
+  </span>
 </header>
 <article id="documentId">
   <div class="container">

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
+## This is the parent module of NimYAML, a package that provides facilities to
-## `YAML <http://yaml.org>`_ character streams. All primitive operations on
+## generate and interpret `YAML <http://yaml.org>`_ character streams. Importing
-## data objects use a `YamlStream <#YamlStream>`_ either as source or as
+## this package will import everything from all subpackages.
-## 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.
 ##
-## As YAML is a strict superset of `JSON <http://json.org>`_, JSON input is
+## There are three high-level APIs which are probably most useful:
-## automatically supported. While JSON is less readable than YAML,
+##
-## this enhances interoperability with other languages.
+## * The serialization API in `serialization <yaml/serialization.html>`_ enables
+##   you to load YAML data directly into native Nim types, and reversely dump
+##   native Nim types as YAML.
+## * The DOM API in `dom <yaml/dom.html>`_ parses YAML files in a tree structure
+##   which you can navigate.
+## * The JSON API in `tojson <yaml/tojson.html>`_ 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 <yaml/stream.html>`_ defines the central type for
+##   stream processing, ``YamlStream``. It also contains definitions and
+##   constructor procs for stream events.
+## * The parser API in `parser <yaml/parser.html>`_ gives you direct access to
+##   the YAML parser's output.
+## * The presenter API in `presenter <yaml/presenter.html>`_ gives you direct
+##   access to the presenter, i.e. the module that renders a YAML character
+##   stream.
+## * The taglib API in `taglib <yaml/taglib.html>`_ 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 <yaml/hints.html>`_ provides a simple proc for
+##   guessing the type of a scalar value.
+## * Finally, some basic types have been placed in `common <yaml/common.html>`_
+##   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

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

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

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
 

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
 

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
 

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
 

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
 

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
 

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