Draft: documentation

docs/.gitignore

@@ -0,0 +1 @@
+book

docs/README.md

@@ -0,0 +1,15 @@
+# Snowman manual
+
+The Snowman manual/documentation is supposed to be both a comprehensive guide to using Snowman and a reference for all the features and commands available in Snowman.
+
+## Building the manual
+
+The manual is build using [mdBook](https://rust-lang.github.io/mdBook/). To build the manual, you need to have `mdBook` installed. 
+
+To build the manual, run:
+
+```sh
+mdbook serve
+```
+
+The manual should now be available at `http://[::1]:3000`.

docs/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["Albin Larsson"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Snowman Manual"

docs/src/SUMMARY.md

@@ -0,0 +1,50 @@
+# Summary
+
+[Introduction](./introduction.md)
+
+- [Installation](./installation.md)
+- [Quick start](./quick-start.md)
+- [Core concepts](./core-concepts.md)
+
+# Reference
+
+- [CLI](./reference/cli.md)
+    - [build](./reference/cli/build.md)
+    - [cache](./reference/cli/cache.md)
+    - [completion](./reference/cli/completion.md)
+    - [new](./reference/cli/new.md)
+    - [server](./reference/cli/server.md)
+    - [version](./reference/cli/version.md)
+- [Template syntax](./reference/template-syntax/index.md)
+    - [Variables](./reference/template-syntax/variables.md)
+    - [Comments](./reference/template-syntax/comments.md)
+    - [Whitespace control](./reference/template-syntax/whitespace-control.md)
+    - [Loops](./reference/template-syntax/loops.md)
+    - [Conditionals](./reference/template-syntax/conditionals.md)
+    - [Includes](./reference/template-syntax/includes.md)
+    - [Layouts](./reference/template-syntax/layouts.md)
+    - [Pipes](./reference/template-syntax/pipes.md)
+- [Template functions](./reference/template-functions.md)
+- [Configuration](./reference/configuration.md)
+    - [snowman.yaml](./reference/snowman-yaml.md)
+    - [views.yaml](./reference/views-yaml.md)
+- [Style guide](./reference/style-guide.md)
+
+# Guides
+
+- [CLI autocompletion](./guides/cli-autocompletion.md)
+- [Continuous integration](./guides/continuous-integration.md)
+- [Managing cache](./guides/managing-cache.md)
+- [Timing builds](./guides/timing-builds.md)
+
+# Recipes
+
+- [Multilangual RDF labels](./recipes/multilangual-rdf-labels.md)
+- [Rendering JSON](./recipes/rendering-json.md)
+- [Rendering XML](./recipes/rendering-xml.md)
+- [Fetching files](./recipes/fetching-files.md)
+- [Reading local files](./recipes/reading-local-files.md)
+- [Retrieving and parsing JSON](./recipes/retrieving-and-parsing-json.md)
+- [Site metadata](./recipes/site-metadata.md)
+- [Reading environment variables](./recipes/reading-environment-variables.md)
+- [Parameterized queries](./recipes/parameterized-queries.md)

docs/src/core-concepts.md

@@ -0,0 +1,13 @@
+# Core concepts
+
+## Terminology
+
+## Template engine
+
+## SPARQL
+
+## Views
+
+## Configuration / `snowman.yaml`
+
+## Cache

docs/src/guides/cli-autocompletion.md

@@ -0,0 +1 @@
+# CLI autocompletion

docs/src/guides/continuous-integration.md

@@ -0,0 +1 @@
+# Continuous integration recipies

docs/src/guides/managing-cache.md

@@ -0,0 +1 @@
+# Managing cache

docs/src/guides/timing-builds.md

@@ -0,0 +1 @@
+# Timing builds

docs/src/installation.md

@@ -0,0 +1,19 @@
+# Installation
+
+Snowman ships as a single binary, and is available for the most commons architectures and operating systems. Check out the [releases page](https://github.com/glaciers-in-archives/snowman/releases) for the latest version. Once downloaded, you should rename it to `snowman` install it by moving it to a directory in your `PATH`.
+
+## Using multiple versions
+
+If you need to use multiple versions of Snowman, you can either rename the binary to something like `snowman-0.5.0` and then symlink it to `snowman` in your `PATH` or use it directly by specifying the path to the binary(`./path/to/snowman`).
+
+## Installing from source
+
+If you would want to compile from source, you can do so:
+
+```sh
+git clone https://github.com/glaciers-in-archives/snowman
+cd snowman
+go build -o snowman
+```
+
+For all possible target operating systems and architectures, see the the [following table](https://www.digitalocean.com/community/tutorials/how-to-build-go-executables-for-multiple-platforms-on-ubuntu-16-04).

docs/src/introduction.md

@@ -0,0 +1,20 @@
+# Introduction
+
+![Header image with template and query](./header.png)
+
+**Snowman is a static site generator for SPARQL backends.**
+
+Snowman's templating system comes with RDF- and SPARQL-tailored features and takes its data from SPARQL queries. Snowman has first-class support for RDF concepts like: Language-tagged literals, IRIs, and XSD datatypes.
+
+## Jump right in
+
+ - [Installation](./installation.md)
+ - [Quick start](./quick-start.md)
+
+## Background
+
+Ever seen a project that models its data in RDF, but then uses a non-RDF technology to render it?
+
+Snowman is designed to address this by allow RDF-based projects to use SPARQL in the user-facing parts of their stack, without sacrificing preformance. Today, Snowman is used to render everything from simple SKOS vocabularies to entire knowledge bases.
+
+Snowman is not a high-level web-framework, actually, turns out people use it for a lot of things like data transformation and APIs! As a result, Snowman is rather unopinionated about how you structure your project, transforming data directly in SPARQL queries? or with the template engine? or both? It's up to you, that said, we have a [style guide and some best practices](./reference/style-guide.md) to help you get started.

docs/src/quick-start.md

@@ -0,0 +1,30 @@
+# Quick start
+
+```
+snowman new  --directory="best-project-name-ever"
+cd best-project-name-ever
+snowman build && snowman server
+```
+
+This will create a new Snowman project in the directory `best-project-name-ever`, build it, and start a local server. You can now visit `http://localhost:8080` to see the built site. To get you started it fetches a few triples from Wikidata, gives you a basic layout and a static file. 
+
+## The project structure
+
+The project structure upon using the `snowman new` command is as follows:
+
+```
+best-project-name-ever
+├── queries # your SPARQL queries go here, create subdirectories to organize them
+│   └── index.rq
+├── static # static files go here, they are copied to the root of the build directory, make subdirectories to modify the output path
+│   └── style.css
+├── templates # your templates go here, create subdirectories to organize them, go beyond HTML!
+    ├── includes # common name for components and partial templates
+    │   └── footer.html
+    ├── layouts # layouts are special templates that wrap other templates
+    │   └── default.html
+    ├── static.html # a page not feed by SPARQL but with full access to the template engine
+    └── index.html # a page feed by SPARQL
+├── snowman.yaml # core configuration go here, like the SPARQL endpoint and site metadata
+└── views.yaml # all your views go here, a view connects a template to a SPARQL query, look for the index.html and static.html in this file
+```

docs/src/recipes/fetching-files.md

@@ -0,0 +1 @@
+# Fetching files

docs/src/recipes/multilangual-rdf-labels.md

@@ -0,0 +1 @@
+# Multilangual RDF labels

docs/src/recipes/parameterized-queries.md

@@ -0,0 +1 @@
+# Parameterized queries

docs/src/recipes/reading-environment-variables.md

@@ -0,0 +1 @@
+# Reading environment variables

docs/src/recipes/reading-local-files.md

@@ -0,0 +1 @@
+# Reading local files

docs/src/recipes/rendering-json.md

@@ -0,0 +1 @@
+# Rendering JSON

docs/src/recipes/rendering-xml.md

@@ -0,0 +1 @@
+# Rendering XML

docs/src/recipes/retrieving-and-parsing-json.md

@@ -0,0 +1 @@
+# Retrieving and parsing JSON

docs/src/recipes/site-metadata.md

@@ -0,0 +1 @@
+# Site metadata

docs/src/reference/cli.md

@@ -0,0 +1,3 @@
+# CLI
+
+Snowman's command line interface (CLI) is the primary way to interact with a Snowman project. The CLI provides a set of commands to manage and build a Snowman project. The CLI is intended for development and continuous integration/ delivery purposes.

docs/src/reference/cli/build.md

@@ -0,0 +1,17 @@
+# `build`
+
+The `build` command is used to build a Snowman project. It reads the configuration file and the views file, and then it fetches the data from the SPARQL endpoint and renders the templates. The output is written to the `site` directory.
+
+```sh
+snowman build
+```
+
+## Flags
+
+ - `--cache` (`-c`) Sets the cache strategy. "available" will use cached SPARQL responses when available and fallback to making queries. "never" will ignore existing cache and will not update or set new cache. (default "available")
+ - `--config` (`-f`) The path to the configuration file. (default "snowman.yaml")
+ - `--help` (`-h`) Shows help for the command.
+ - `--verbose` (`-v`) Enables verbose output.
+ - `--static` (`-s`) Only update static files, do not fetch data or render templates.
+ - `--timeit` (`-t`) Print the time it took to build the site.
+

docs/src/reference/cli/cache.md

@@ -0,0 +1,15 @@
+# `cache`
+
+The `cache` command is a powerful tool used to manage the query cache of a Snowman project. By defualt, Snowman will cache SPARQL responses to avoid making the same query multiple times even across multiple builds. This command allows you to inspect and clear all or subsets of the cache.
+
+```sh
+snowman cache [optional-query] [optional-query-arguments]
+```
+
+## Flags
+
+ - `--invalidate` (`-i`) Invalidates the cache for the given scope. If no query is given, the entire cache is invalidated. If a query but no query arguments are given, the cache for all queries using the given query file is invalidated.
+ - `--unused` Sets the scope to all queries not used during the last build.
+ - `--help` (`-h`) Shows help for the command.
+ - `--verbose` (`-v`) Enables verbose output.
+ - `--timeit` (`-t`) Shows the time it took to execute the command.

docs/src/reference/cli/completion.md

@@ -0,0 +1,18 @@
+# `completion`
+
+The `completion` command generates shell completion scripts for the Snowman CLI.
+
+```sh
+snowman completion <shell>
+```
+
+## Arguments
+
+- `bash` Generates a bash completion script.
+- `zsh` Generates a zsh completion script.
+- `fish` Generates a fish completion script.
+- `powershell` Generates a powershell completion script.
+
+## Flags
+
+- `--help` (`-h`) Shows help for the command if used in combination with an argument it will show installation instructions for the completion script.

docs/src/reference/cli/new.md

@@ -0,0 +1,14 @@
+# `new`
+
+The `new` command is used to scaffold a new Snowman project by setting up a basic project structure and configuration files.
+
+```sh
+snowman new  --directory="best-project-name-ever"
+```
+
+See the [quick start](../quick-start.md) for more information about the generated project structure.
+
+## Flags
+
+- `--directory` (`-d`) The name of the directory to create the project in. (default "my-new-project")
+- `--help` (`-h`) Shows help for the command.

docs/src/reference/cli/server.md

@@ -0,0 +1,13 @@
+# `server`
+
+The `server` command is used to start a local server to serve the built site. It's only intended for development purposes.
+
+```sh
+snowman server
+```
+
+## Flags
+
+ - `--address` (`-a`) The address to listen on. (default "127.0.0.1")
+ - `--help` (`-h`) Shows help for the command.
+ - `--port` (`-p`) The port to listen on. (default "8000")

docs/src/reference/cli/version.md

@@ -0,0 +1,23 @@
+# `version`
+
+The `version` command prints the version of Snowman.
+
+```sh
+snowman version
+```
+
+## Format
+
+The output is a single line consisting of three parts separated by spaces:
+
+```
+Snowman 0.5.0-development linux/amd64
+```
+
+1. The name of the application, allways `Snowman`.
+2. The version of the application([semver](https://semver.org/)).
+3. The operating system and architecture the binary was built for.
+
+## Flags
+
+- `--help` (`-h`) Shows help for the command.

docs/src/reference/configuration.md

@@ -0,0 +1 @@
+# Configuration

docs/src/reference/snowman-yaml.md

@@ -0,0 +1 @@
+# snowman.yaml

docs/src/reference/style-guide.md

@@ -0,0 +1 @@
+# Style guide

docs/src/reference/template-functions.md

@@ -0,0 +1 @@
+# Template functions

docs/src/reference/template-syntax/comments.md

@@ -0,0 +1,22 @@
+# Comments
+
+Comments are not rendered in the output. They are useful for adding notes to the source code that are not meant to be displayed in the output.
+
+```
+{{/* my very important comment */}}
+```
+
+Comments can span multiple lines.
+
+```
+{{/*
+  This is a comment
+  that spans multiple lines
+*/}}
+```
+
+Comments can also contain trim markers to remove surrounding whitespace. To learn more about trim makers see the chapter on whitespace control.
+
+```
+{{- /* this is a comment with trim markers */ -}}
+```

docs/src/reference/template-syntax/conditionals.md

@@ -0,0 +1 @@
+# Conditionals

docs/src/reference/template-syntax/includes.md

@@ -0,0 +1 @@
+# Includes

docs/src/reference/template-syntax/index.md

@@ -0,0 +1,3 @@
+# Template syntax
+
+Snowman uses [Go templates](https://golang.org/pkg/text/template/) to render the output of a Snowman project. While Go provides their own documentation on how to use its templatings systen we do the same here but with a focus on how to use it with Snowman.

docs/src/reference/template-syntax/layouts.md

@@ -0,0 +1 @@
+# Layouts

docs/src/reference/template-syntax/loops.md

@@ -0,0 +1 @@
+# Loops

docs/src/reference/template-syntax/pipes.md

@@ -0,0 +1 @@
+# Pipes

docs/src/reference/template-syntax/variables.md

@@ -0,0 +1 @@
+# Variables

docs/src/reference/template-syntax/whitespace-control.md

@@ -0,0 +1,35 @@
+# Whitespace control
+
+Snowman templates renders everything between code blocks and comments including whitespace and line feeds. As a result the output can look messy. To control the extra white whitespace in the output you can use trim markers.
+
+Considering the following example.
+
+```
+<ul>
+{{ range .foos }}
+    <li>list item</li>
+{{ end }}
+</ul>
+```
+
+The `{{ range .foos }}` and `{{ end }}` blocks are sourrounded line breaks which will be rendered in the output. To remove the extra whitespace you can use trim markers.
+
+```
+<ul>
+{{- range .foos -}}
+    <li>list item</li>
+{{- end -}}
+</ul>
+```
+
+The `-` is optional and can be placed on either side of the block. The following example will render in the same way as the previous example. 
+
+```
+<ul>{{ range .foos -}}
+    <li>list item</li>
+{{- end }}</ul>
+```
+
+You can also use trim markers with comments:
+
+{{- /* this is a comment with trim markers */ -}}

docs/src/reference/views-yaml.md

@@ -0,0 +1 @@
+# views.yaml