Merge pull request #70 from nils-a/feature/GH-65

(#65) updated documentation

.gitignore

@@ -338,9 +338,14 @@ healthchecksdb
 
 # Cake
 tools/**
-!tools/packages.config
 
 # Build Related
 BuildArtifacts/*
 
+# Wyam
+config.wyam.dll
+config.wyam.hash
+config.wyam.packages.xml
+
+
 .DS_Store

docs/input/_Bottom.cshtml

@@ -0,0 +1,55 @@
+<a class="github-button" href="https://github.com/cake-contrib/Cake.Chocolatey.Module" target="_blank">
+    <i class="fa fa-github"></i>
+    GitHub
+</a>
+<a class="discussion-button" href="https://github.com/cake-build/cake/discussions" target="_blank">
+    <i class="fa fa-github"></i>
+    Discussion
+</a>
+
+<script type="text/javascript" src="@Context.GetLink("/assets/js/anchor.min.js")"></script>
+<script type="text/javascript" src="@Context.GetLink("/assets/js/clipboard.min.js")"></script>
+<script type="text/javascript">
+    anchors.options.placement = 'left';
+    anchors.add('#content h1:not(.no-anchor), #content h2:not(.no-anchor), #content h3:not(.no-anchor), #content h4:not(.no-anchor)');
+
+    var snippets = document.querySelectorAll("pre > code");
+    [].forEach.call(snippets, function(snippet) {
+        snippet.insertAdjacentHTML("beforebegin", "<button class='btn-copy' data-clipboard-snippet><img class='clippy' width=13 src='@Context.GetLink("/assets/images/clippy.svg")' alt='Copy to clipboard'></button>");
+    });
+    var clipboardSnippets = new Clipboard('[data-clipboard-snippet]', {
+        target: function(trigger) {
+            return trigger.nextElementSibling;
+        }
+    });
+    clipboardSnippets.on('success', function(e) {
+        e.clearSelection();
+        showTooltip(e.trigger, "Copied!");
+    });
+    clipboardSnippets.on('error', function(e) {
+        showTooltip(e.trigger, fallbackMessage(e.action));
+    });
+    var btns = document.querySelectorAll('.btn-copy');
+    for (var i = 0; i < btns.length; i++) {
+        btns[i].addEventListener('mouseleave', function(e) {
+            e.currentTarget.setAttribute('class', 'btn-copy');
+            e.currentTarget.removeAttribute('aria-label');
+        });
+    }
+    function showTooltip(elem, msg) {
+        elem.setAttribute('class', 'btn-copy tooltipped tooltipped-s');
+        elem.setAttribute('aria-label', msg);
+    }
+    function fallbackMessage(action) {
+        var actionMsg = '';
+        var actionKey = (action === 'cut' ? 'X' : 'C');
+        if (/iPhone|iPad/i.test(navigator.userAgent)) {
+            actionMsg = 'No support :(';
+        } else if (/Mac/i.test(navigator.userAgent)) {
+            actionMsg = 'Press ⌘-' + actionKey + ' to ' + action;
+        } else {
+            actionMsg = 'Press Ctrl-' + actionKey + ' to ' + action;
+        }
+        return actionMsg;
+    }
+</script>

docs/input/_Footer.cshtml

@@ -0,0 +1,5 @@
+<p class="text-muted">
+    Copyright &copy; <a href="http://github.com/cake-contrib" target="_blank">Cake Contributions</a> and <a href="https://github.com/cake-contrib/Cake.Chocolatey.Module/graphs/contributors" target="_blank">contributors</a>.
+    <br/>
+    Website generated by <a href="https://github.com/Wyamio/Wyam" target="_blank">Wyam</a>
+</p>

docs/input/assets/css/highlight.css

@@ -0,0 +1,99 @@
+/*
+
+github.com style (c) Vasily Polovnyov <vast@whiteants.net>
+
+*/
+
+.hljs {
+  display: block;
+  overflow-x: auto;
+  padding: 0.5em;
+  color: #333;
+  background: #f8f8f8;
+}
+
+.hljs-comment,
+.hljs-quote {
+  color: #998;
+  font-style: italic;
+}
+
+.hljs-keyword,
+.hljs-selector-tag,
+.hljs-subst {
+  color: #333;
+  font-weight: bold;
+}
+
+.hljs-number,
+.hljs-literal,
+.hljs-variable,
+.hljs-template-variable,
+.hljs-tag .hljs-attr {
+  color: #008080;
+}
+
+.hljs-string,
+.hljs-doctag {
+  color: #d14;
+}
+
+.hljs-title,
+.hljs-section,
+.hljs-selector-id {
+  color: #900;
+  font-weight: bold;
+}
+
+.hljs-subst {
+  font-weight: normal;
+}
+
+.hljs-type,
+.hljs-class .hljs-title {
+  color: #458;
+  font-weight: bold;
+}
+
+.hljs-tag,
+.hljs-name,
+.hljs-attribute {
+  color: #000080;
+  font-weight: normal;
+}
+
+.hljs-regexp,
+.hljs-link {
+  color: #009926;
+}
+
+.hljs-symbol,
+.hljs-bullet {
+  color: #990073;
+}
+
+.hljs-built_in,
+.hljs-builtin-name {
+  color: #0086b3;
+}
+
+.hljs-meta {
+  color: #999;
+  font-weight: bold;
+}
+
+.hljs-deletion {
+  background: #fdd;
+}
+
+.hljs-addition {
+  background: #dfd;
+}
+
+.hljs-emphasis {
+  font-style: italic;
+}
+
+.hljs-strong {
+  font-weight: bold;
+}

docs/input/assets/css/override.less

@@ -0,0 +1,157 @@
+/* our title is quite long */
+.main-header .logo {
+    font-size: 18px;
+}
+
+/* Front page */
+.logo-small {
+    color: #4EABDD;
+    font-size: 50px;
+}
+
+/* Control the margin for bootstrap alert boxes */
+.alert > p {
+    margin-top: 0px;
+}
+
+/* Search box */
+#navbar-collapse, #navbar-collapse nav {
+    width: 100%;
+}
+
+.navbar-nav {
+    float: none;
+}
+
+.navbar-right {
+    margin-right: 15px;
+}
+
+@media (max-width: 767px) {
+    .navbar-right {
+        margin-left: 0px;
+    }
+}
+
+/* Control the look and feel of the copy box applied to code sections */
+.btn-copy[disabled] .clippy {
+    opacity: .3;
+}
+pre .btn-copy {
+    -webkit-transition: opacity 0.3s ease-in-out;
+    -o-transition: opacity 0.3s ease-in-out;
+    transition: opacity 0.3s ease-in-out;
+    opacity: 0;
+    padding: 2px 6px;
+    float: right;
+}
+pre:hover .btn-copy {
+    opacity: 1;
+}
+.tooltipped {
+    position: relative
+}
+.tooltipped:after {
+    position: absolute;
+    z-index: 1000000;
+    display: none;
+    padding: 5px 8px;
+    font: normal normal 11px/1.5 Helvetica, arial, nimbussansl, liberationsans, freesans, clean, sans-serif, "Segoe UI Emoji", "Segoe UI Symbol";
+    color: #fff;
+    text-align: center;
+    text-decoration: none;
+    text-shadow: none;
+    text-transform: none;
+    letter-spacing: normal;
+    word-wrap: break-word;
+    white-space: pre;
+    pointer-events: none;
+    content: attr(aria-label);
+    background: rgba(0, 0, 0, 0.8);
+    border-radius: 3px;
+    -webkit-font-smoothing: subpixel-antialiased
+}
+.tooltipped:before {
+    position: absolute;
+    z-index: 1000001;
+    display: none;
+    width: 0;
+    height: 0;
+    color: rgba(0, 0, 0, 0.8);
+    pointer-events: none;
+    content: "";
+    border: 5px solid transparent
+}
+.tooltipped:hover:before, .tooltipped:hover:after, .tooltipped:active:before, .tooltipped:active:after, .tooltipped:focus:before, .tooltipped:focus:after {
+    display: inline-block;
+    text-decoration: none
+}
+.tooltipped-s:after, .tooltipped-se:after, .tooltipped-sw:after {
+    top: 100%;
+    right: 50%;
+    margin-top: 5px
+}
+.tooltipped-s:before, .tooltipped-se:before, .tooltipped-sw:before {
+    top: auto;
+    right: 50%;
+    bottom: -5px;
+    margin-right: -5px;
+    border-bottom-color: rgba(0, 0, 0, 0.8)
+}
+
+@font-family-sans-serif:  "Roboto", Helvetica, Arial, sans-serif;
+
+/* For GitHub */
+.bottom-footer {
+	margin-bottom: 40px !important;  // Make room for GitHub buttons
+}
+
+.discussion-button {
+	z-index: 100;
+	position: fixed;
+	bottom: 0px;
+	right: 80px;
+	padding: 1em 3em;
+	background-color: #367fa9;
+	border: 0;
+	border-top-left-radius: 0.5em;
+	border-top-right-radius: 0.5em;
+	font-family: sans-serif;
+	font-size: 9pt;
+	text-transform: uppercase;
+	text-align: center;
+	text-decoration: none;
+	cursor: pointer;
+	cursor: hand;
+	-webkit-transition: all .3s ease;
+	transition: all .3s ease;
+	color: #fff;
+	a, a:active, a:hover, a:focus {
+		color: #fff;
+	}
+}
+
+.github-button {
+	z-index: 100;
+	position: fixed;
+	bottom: 0px;
+	right: 255px;
+	padding: 1em 3em;
+	background-color: #367fa9;
+	border: 0;
+	border-top-left-radius: 0.5em;
+	border-top-right-radius: 0.5em;
+	font-family: sans-serif;
+	font-size: 9pt;
+	text-transform: uppercase;
+	text-align: center;
+	text-decoration: none;
+	cursor: pointer;
+	cursor: hand;
+	-webkit-transition: all .3s ease;
+	transition: all .3s ease;
+	color: #fff;
+	a, a:active, a:hover, a:focus {
+		color: #fff;
+	}
+}

docs/input/docs/installation/Setup.md

@@ -1,17 +1,23 @@
-Due to the fact that Cake Modules are extending and altering the internals of the Cake, the Module Assembly needs to be loaded prior to the main Cake execution.  As a result, the only place that this can really happen is during the bootstrapping phase.  If you use the [latest version of the default bootstrapper](https://github.com/cake-build/resources/commit/3d112812353d714dad142c41f170b949f4a2eb2f) this process is made very easy.  All you need to do is the following.
+---
+Title: Setup
+---
 
-1. Add a modules folder into your tools folder
-2. Add a packages.config file into the newly created modules folder
-3. Add the name and version of the Module that you want to use.  **NOTE:** At this point, the assumption is that you are hosting the Module on NuGet.org.  If this is not the case, then additional steps would be required.
-4. An example packages.config file is shown below:
+# Installation
 
-```
-<?xml version="1.0" encoding="utf-8"?>
-<packages>
-	<package id="Cake.Chocolatey.Module" version="0.1.0" />
-</packages>
-```
+Due to the fact that Cake Modules are extending and altering the internals of Cake, the module assembly needs to be loaded prior to the main Cake execution. As a result, the only place that this can really happen is during the bootstrapping phase. If you use the latest version of the default bootstrapper this process is made very easy. All you need to do is the following.
 
-5. Run the build as normal.  During the Cake Execution, it will recognise the Module Assembly which as been restored into the `tools/modules` folder, and load it.
+1. Add the following line in your `build.cake`:
 
-**NOTE:** Similar to the recommendation [here](http://cakebuild.net/docs/tutorials/getting-started) regarding only checking in your packages.config and not the entire contents of the Cake tools folder, the same recommendation is applied here.  Only check-in the packages.config file in the modules folder, and not the entire contents.
+   ```cs
+   #module nuget:?package=Cake.Chocolatey.Module&version=<version>
+   ```
+1. For Cake versions before `1.0.0`, run the build with argument `--bootstrap` (i.e. `./build.ps1 --bootstrap`).
+
+   This will restore the module assembly into the `tools/Modules` folder
+1. Run the build as normal. During Cake's execution, it will recognize the module assembly which has been restored into the `tools/Modules` folder, and load it.
+
+:::{.alert .alert-info}
+**NOTE**
+
+These steps assume you are using the default package source repository (community feed). Custom feeds require additional steps.
+:::