Merge pull request #18 from pietroppeter/add-docs

nimibook docs + 2 fixes + 1 feature (cfg) + 1 refactor

.gitignore

@@ -4,4 +4,4 @@
 !docs/fonts
 !docs/js
 docs/
-book/toc.json
+book/book.json

README.md

@@ -1,60 +1,52 @@
 # nimibook
 
-A port of [mdbook](https://rust-lang.github.io/mdBook/index.html)
-to [nim](https://nim-lang.org/),
-powered by [nimib](https://pietroppeter.github.io/nimib/).
-
-Currently a PoC with minimal functionality hacked together to support [sciNim/getting-started](https://github.com/SciNim/getting-started).
-
-# Usage
-
-* 1) Write your content using [nimib](https://pietroppeter.github.io/nimib/) in the ``book`` folder.
-
-* 2) Use the Toc DSL to link chapters to Nim file in ``genbook.nim``.
-
-* 3) Generate your books in the ``docs`` folder using ``nimble genbook``.
-
-<!-- index.hbs adapted from mdbook to mustache
-required fields:
-- language
-- default_theme
-- description
-- path_to_root
-- preferred_dark_theme
-- theme_option (light, rust, coal, navy, ayu)
-- book_title
-optional stuff:
-- is_print
-- base_url
-- favicon_svg/favicon_png
-- print_enable
-- additional_css
-- mathjax_support
-- search_enable
-- git_repository_url (git_repository_icon)
-- git_repository_edit_url
-- previous (link)
-- next (link)
-- livereload
-- google_analytics
-- playground_line_numbers
-- playground_copyable
-- playground_js
-- search_js
-- additional_js
-partials:
-- head
-- header
-- toc
-assets required:
-- css/variables.css
-- css/general.css
-- css/chrome.css
-- FontAwesome/css/font-awesome.css
-- highlight.css
-- tomorrow-night.css
-- ayu-highlight.css
-- clipboard.min.js
-- highlight.js
-- book.js
+**nimibook** is a port of [mdbook] to [Nim], powered by [nimib].
+Nimibook allows to create a nice looking book from nim code and markdown,
+making sure that nim code is running correctly and being able to incorporate code outputs in the final book.
+An example book is [nimibook documentation][nimibook] itself.
+
+[mdBook] is a command line tool and Rust crate to create books
+using Markdown (as by the CommonMark specification) files.
+It's very similar to [Gitbook], which is a command line tool (and Node.js library)
+for building beautiful books using GitHub/Git and Markdown (or AsciiDoc).
+
+[nimib] is a Nim library to convert your Nim code and its outputs to html documents.
+The html output can be easily customized thanks to [nim-mustache],
+and this is what allows it to use it to build nimibook.
+_nimib documents_ are normal nim files which use nimib library to produce an output document.
+
+The Markdown dialect supported by both nimib and nimibook is the subset of [Github Flavored Markdown][GFM]
+provided by [nim-markdown]. For a quick reference of supported syntax see the [cheatsheet].
+
+### Status
+
+nimibook currently provides minimal functionality to create a book, notably missing is
+a command line interface to automate common task (e.g. initialization of a new nimibook).
+
+## Installation
+
+To be able to use nimibook, currently the only way is to recreate the same content of the repository
+and adjust it to your content. You can do that using the template feature from github
+or with a checkout of the repo and copying and pasting.
+
+Discussion of further options is ongoing in [issue #12](https://github.com/pietroppeter/nimibook/issues/12).
+
+## Usage
+
+1. Write your content using [nimib] or simple markdown files in the ``book`` folder.
+2. Use the Toc DSL to link chapters to content in ``genbook.nim``.
+3. Generate your books in the ``docs`` folder using ``nimble genbook``.
+
+<!--refs-->
+[mdbook]: https://rust-lang.github.io/mdBook/index.html
+[Nim]: https://nim-lang.org/
+[nimib]: https://pietroppeter.github.io/nimib/
+[Gitbook]: https://github.com/GitbookIO/gitbook
+[nim-mustache]: https://github.com/soasme/nim-mustache
+[nimibook]: https://pietroppeter.github.io/nimibook/
+[GFM]: https://github.github.com/gfm/
+[nim-markdown]: https://github.com/soasme/nim-markdown
+
+<!--SKIP
+All content before this sign is replicated in the Introduction chapter of nimibook documentation
 -->

book/configuration.nim

@@ -0,0 +1,54 @@
+import nimib, nimibook
+import std / [os, strutils, strscans, strformat]
+
+nbInit
+nbUseNimibook
+
+# the following is very dependent on how source is written
+proc readBookConfigFields: seq[string] =
+  # current folder is docs
+  let src = "../src/nimibook/types.nim"
+  var process = false
+  var field, typ, description: string
+  for line in src.lines:
+    # debugEcho line
+    if line.strip.startsWith("Book"):
+      # debugEcho ">start processing"
+      process = true
+      continue
+    if line.strip.startsWith("#"):
+      # debugEcho ">skip"
+      continue
+    if line.strip.startsWith("toc"):
+      # debugEcho ">stop processing"
+      break
+    if process and line.contains("##"):
+      # debugEcho ">match"
+      description = line.split("##")[1].strip
+      field = line.split("##")[0].split("*:")[0].strip
+      typ = line.split("##")[0].split("*:")[1].strip
+      result.add fmt"* **{field}** (`{typ}`): {description}"
+    # else: debugEcho ">noMatch"
+
+let fieldList = readBookConfigFields().join("\n")
+
+nbText: fmt"""
+# Configuration
+
+Book configuration is done with the `Book` object that has been created with `newBookFromToc`.
+
+The `Book` object has the following fields which are relevant for the documentation:
+
+{fieldList}
+
+Notes:
+
+* for consistency with template values, we use snake case for fields of this object.
+* the book object replicates functionalities available in mdbook
+* relevant documentation for mdbook is in this two pages:
+    - <https://rust-lang.github.io/mdBook/format/theme/index-hbs.html>
+    - <https://rust-lang.github.io/mdBook/format/config.html>
+* if not indicated otherwise, these fields are present in `document.mustache` and they are directly adapted from `index.hbs`
+* documentation comments above come directly from mdbook documentation (unless otherwise stated)
+"""
+nbSave

book/content.nim

@@ -0,0 +1,24 @@
+import nimib, nimibook
+nbInit
+nbUseNimibook
+
+nbText: """
+# Content
+
+The content of a chapter of a book can be a standard Markdown file or a nim file.
+
+For the nim file the structure is the following:
+
+```nim
+import nimib, nimibook
+... # other imports
+
+nbInit # initializes a nimib document
+nbUseNimibook # overrides nimib defaults with nimibooks and loads book configuration
+
+... # content of chapter using nbText, nbCode and other nimib functionalities
+
+nbSave # save the document to html output
+```
+""" # todo: highlight nim code
+nbSave

book/document.mustache

@@ -1,7 +1,7 @@
 <!DOCTYPE HTML>
 <html lang="{{ language }}" class="sidebar-visible no-js {{ default_theme }}">
     <head>
-        <!-- Book generated using mdBook -->
+        <!-- Book generated using nimibook -->
         <meta charset="UTF-8">
         <title>{{ title }}</title>
         {{#is_print }}
@@ -20,7 +20,7 @@
         <meta name="viewport" content="width=device-width, initial-scale=1">
         <meta name="theme-color" content="#ffffff" />
 
-        {{&favicon_whale}}
+        {{&favicon_escaped}}
         {{#favicon_svg}}
         <link rel="icon" href="{{ path_to_root }}favicon.svg">
         {{/favicon_svg}}

book/index.nim

@@ -1,10 +1,13 @@
-include nimibook / prelude
-nbText: """# Introduction
+import nimib, nimibook
+import strutils
+nbInit
+nbUseNimibook # overrides nimib defaults with nimibooks and loads book configuration
 
-I should say something very wise about this book.
+proc readFileUntil(filename: string, text: string): string =
+  for line in filename.lines:
+    if line.startsWith(text):
+      return result
+    result &= line & '\n'
 
-Instead I will just post some nim code:
-"""
-nbCode:
-  echo "hello mdbook!"
+nbText: "../README.md".readFileUntil("<!--SKIP")
 nbSave

book/tasks.nim

@@ -0,0 +1,20 @@
+import nimib, nimibook
+import osproc, sugar, strutils, strformat
+
+nbInit
+nbUseNimibook
+
+var tasks: string
+withDir("..".AbsoluteDir):
+  tasks = execProcess("nimble", args=["tasks"], options={poUsePath})
+
+let taskList = collect(newSeq):
+  for line in tasks.strip.splitLines:
+    "* `nimble " & line.replace("        ", "`: ")
+
+nbText: fmt"""
+# Tasks
+
+{taskList.join("\n")}
+"""
+nbSave

book/tocdsl.nim

@@ -0,0 +1,26 @@
+import nimib, nimibook
+nbInit
+nbUseNimibook
+
+nbText: """
+# Table of Contents DSL
+
+The table of content supports (numbered) chapters (`entry`),
+sections (`section`) and draft chapters (`draft`, not numbered).
+
+Here is an example on how it looks like
+```nim
+import nimibook, os # os is used inside Toc DSL
+
+let book = newBookFromToc("Example book", "book"):
+  entry("Introduction", "index") # .nim extension is optional
+  entry("Pure Markdown", "pure.md") # for md files you need to use extension
+  # every entry in this section will have a path relative to basics
+  section("Basics", "basics/index.nim"):
+    section("Plotting", "plotting.nim"): # nested sections
+      entry("Data Manipulation", "data_manipulation")
+    entry("Models", "models") 
+  draft("Contributors", "misc/but/very/far/contributors")
+```
+""" # todo: highlight nim code
+nbSave

book/tocexample/back_to_parent.md

@@ -0,0 +1 @@
+# Back to parent section

book/tocexample/draft.md

@@ -0,0 +1 @@
+# Draft chapter

book/tocexample/index.md

@@ -0,0 +1 @@
+# Example toc structure

book/tocexample/nested.md

@@ -0,0 +1 @@
+# Nested section

book/tocexample/nested_entry.md

@@ -0,0 +1 @@
+# Entry in nested section

genbook.nim

@@ -1,21 +1,16 @@
-import nimibook, os
+import nimibook, os # os is used inside Toc DSL
 
-let toc = newToc("Example", "book"):
-  entry("Introduction", "index")
-  entry("Pure Markdown", "pure.md")
-  # .nim extension is optionnal but you can add it if you want to
-  section("Basics", "basics/index.nim"):
-    section("Plotting", "plotting.nim"):
-      entry("Data Manipulation", "data_manipulation")
-    entry("Models", "models")
-  draft("Contributors", "misc/but/very/far/contributors")
+var book = newBookFromToc("nimibook", "book"):
+  section("Introduction", "index"): # .nim extension is optional
+    entry("Content", "content")
+    entry("Toc DSL", "tocdsl")
+    entry("Configuration", "configuration")
+    entry("Tasks", "tasks")
+  section("Example toc structure", "tocexample/index.md"):
+    section("Nested section", "nested.md"):
+      entry("Entry in nested section", "nested_entry.md")
+    entry("Back to parent section", "back_to_parent.md")
+    draft("Draft chapter", "draft.md")
 
-when defined(printToc):
-  import print
-  print toc
-elif defined(dumpToc):
-  dump toc
-elif defined(cleanToc):
-  clean toc
-else:
-  publish toc
+book.git_repository_url = "https://github.com/pietroppeter/nimibook"
+nbBookTasks