Update the generated documentation

.jsdoc.conf.json

@@ -4,7 +4,7 @@
         "dictionaries": ["jsdoc"]
     },
     "source": {
-        "include": ["src", "package.json", "README.md"],
+        "include": ["lib/src", "package.json", "README.md"],
         "includePattern": ".js$",
         "excludePattern": "(node_modules/|docs)"
     },

.npmignore

@@ -1,5 +1,6 @@
 lib/
 docs/
+tasks/
 test/
 node_modules/
 gulpfile.js

docs/_data/changelog-examples.yml

@@ -0,0 +1,4 @@
+-
+    name: 'Custom changelog'
+    description: 'Create a changelog with a custom filename'
+    code: 'gren changelog --generate --override --changelog-filename=RELEASE_NOTES.md'

docs/_data/changelog-options.yml

@@ -0,0 +1,10 @@
+-
+    short: '-G'
+    name: generate
+    description: 'Generate the changelog with gren rather then using the repo releases'
+-
+    short: '-f'
+    name: changelog-filename
+    valueType: '<filename.md>'
+    description: 'The name of the changelog file. [CHANGELOG.md]'
+    defaultValue: CHANGELOG.md

docs/_data/global-options.yml

@@ -0,0 +1,71 @@
+-
+    short: '-u'
+    name: username
+    valueType: '<repo owner>'
+    description: 'The username of the repo e.g. github-tools'
+-
+    short: '-r'
+    name: repo
+    valueType: '<repository name>'
+    description: 'The repository name e.g. github-release-notes'
+-
+    short: '-T'
+    name: token
+    valueType: '<github token>'
+    description: 'The token generated with repo access'
+-
+    short: '-au'
+    name: api-url
+    valueType: '<url>'
+    description: 'Override the GitHub API URL, allows gren to connect to a private GHE installation'
+-
+    short: '-o'
+    name: override
+    description: 'Override the release notes if exist.'
+-
+    short: '-t'
+    name: tags
+    valueType: '<new-tag>..<old-tag>'
+    description: 'Write release notes for <new-tag> using data collected until <old-tag>. If only one tag is specified, will use data until the previous tag. To run gren for all the tags, use --tags=*'
+-
+    short: '-D'
+    name: data-source
+    valueType: '<issues|commits|milestones>'
+    description: 'The informations you want to use to build release notes. [issues]'
+    defaultValue: issues
+-
+    short: '-im'
+    name: include-messages
+    valueType: '<merge|commits|all>'
+    description: 'Filter the messages added to the release notes. Only used when --data-source used is commits [commits]'
+    defaultValue: commits
+-
+    short: '-p'
+    name: prefix
+    valueType: '<name prefix>'
+    description: 'Add a prefix to the tag version. e.g. ''v'''
+-
+    short: '-g'
+    name: group-by
+    valueType: '<label>'
+    description: 'Group the issues using the labels as group headings. You can set custom headings for groups of labels from a configuration file.'
+-
+    short: '-L'
+    name: ignore-labels
+    valueType: '<label1>,<label2>'
+    description: 'Ignore the specified labels.'
+-
+    short: '-I'
+    name: ignore-issues-with
+    valueType: '<label1>,<label2>'
+    description: 'Ignore issues that contains one of the specified labels.'
+-
+    short: '-mm'
+    name: milestone-match
+    valueType: '<prefix>'
+    description: 'The title that the script needs to match to link the release to the milestone. e.g. v will match v0.1.0 [Release {{tag_name}}]'
+    defaultValue: 'Release {{tag_name}}'
+-
+    short: '-m'
+    name: only-milestones
+    description: 'Add to the release bodies only the issues that have a milestone'

docs/_data/gren-examples.yml

@@ -0,0 +1,17 @@
+-
+    name: Help
+    description: 'Show the general help of the gren tool'
+    code: gren
+-
+    code: 'gren --help'
+-
+    code: 'gren -h'
+-
+    name: Version
+    description: 'Show the using version'
+    code: 'gren --version'
+-
+    code: 'gren -v'
+-
+    description: 'Get help for the release options'
+    code: 'gren help release'

docs/_data/release-examples.yml

@@ -0,0 +1,29 @@
+-
+    name: 'Manual repo infos'
+    description: 'Run gren outside of the project folder.'
+    code: 'gren release --username=REPO_USER --repo=REPO_NAME'
+-
+    name: 'Override an existing release'
+    description: 'By default, `gren` won''t override an existing release and it will flag `Skipping 4.0.0 (use --override to replace it)`. If you want to override, as it suggests, use:'
+    code: 'gren release --override'
+-
+    name: 'Create release notes for a specific tag'
+    description: 'Get the commits or issues closed between the specified tag and the one before.'
+    code: 'gren release --tags=4.0.0'
+-
+    description: 'Get the commits or the issues between two specified tags.'
+    code: 'gren release --tags=4.0.0..3.0.0'
+-
+    name: 'Create release notes for all the tags'
+    description: 'Get the commits or issues closed between the specified tag and the one before.'
+    code: 'gren release --tags=*'
+-
+    description: '_`all` instead of `*` will be deprecated in 1.0.0_ '
+    code: 'gren release --tags=all'
+-
+    name: 'Work with milestones'
+    description: 'Create release notes for a tag using the belonging to a milestone that matches the name of the tag. e.g. If the tag is 4.0.0, `gren` is going to match the milestone _"Release 4.0.0"_.'
+    code: 'gren release --data-source=milestones --milestone-match="Release {{tag_name}}"'
+-
+    description: 'Otherwise, you can just filter the issues that belong to _a_ milestone'
+    code: 'gren release --only-milestones'

docs/_data/release-options.yml

@@ -0,0 +1,8 @@
+-
+    short: '-d'
+    name: draft
+    description: 'Set the release notes as a draft.'
+-
+    short: '-pr'
+    name: prerelease
+    description: 'Set the release as a prerelease.'

docs/_includes/functions/show-examples.html

@@ -0,0 +1,22 @@
+## {{ include.title }}
+
+{% for example in include.examples %}
+
+{% if example.name %}
+---
+
+#### `{{ example.name }}`
+{% endif %}
+
+{% if example.description %}
+{{ example.description }}
+{% endif %}
+
+{% if example.code %}
+```
+{{ example.code }}
+```
+{% endif %}
+
+{% endfor %}
+

docs/_includes/functions/show-options.html

@@ -0,0 +1,20 @@
+## {{ include.title }}
+
+{% for option in include.options %}
+
+#### `{{ option.name }}`
+
+{% if option.defaultValue == null %}
+    {{ option.description }}
+{% else %}
+    {% assign defaultValue = '[' | append: option.defaultValue | append: ']' %}
+
+    {{ option.description | replace_first:defaultValue, '' }}
+{% endif %}
+
+{:.full}
+| _short:_ `{{ option.short }}` {% if option.valueType != null %} | _value:_ `{{ option.valueType }}` {% endif %} {% if option.defaultValue != null %} | _default_: `{{ option.defaultValue }}` {% endif %} |
+
+---
+
+{% endfor %}

docs/_sass/_github-highlighting.scss

@@ -2,16 +2,6 @@ pre {
     font: 12px Consolas, "Liberation Mono", Menlo, Courier, monospace;
 }
 
-body {
-  -webkit-text-size-adjust: 100%;
-  text-size-adjust: 100%;
-  color: #333;
-  font-family: "Helvetica Neue", Helvetica, "Segoe UI", Arial, freesans, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
-  font-size: 16px;
-  line-height: 1.6;
-  word-wrap: break-word;
-}
-
 a {
   background-color: transparent;
 }

docs/_sass/_layout.scss

@@ -143,28 +143,16 @@
 
     .post-content {
         margin-bottom: $spacing-unit;
-        /*
-        h2 {
-            font-size: 32px;
-
-            @include media-query($on-laptop) {
-                font-size: 28px;
-            }
-        }
-
-        h3 {
-            font-size: 26px;
-
-            @include media-query($on-laptop) {
-                font-size: 22px;
-            }
-        }
+    }
 
-        h4 {
-            font-size: 20px;
+/* gren
+ * ============================================== */
+    .full {
+        display: table;
+        table-layout: fixed;
+        width: 100%
+    }
 
-            @include media-query($on-laptop) {
-                font-size: 18px;
-            }
-        } */
+    .full td:first-child {
+        width: 100px;
     }

docs/concept.md

@@ -0,0 +1,98 @@
+---
+layout: default
+title: Concept
+---
+
+{:.page-heading}
+# Concept
+
+## Motivation
+
+Everyone loves neat, transparent, informative release notes.
+
+Everyone would also rather avoid maintaining them. What a hassle to have to evaluate what issues have been solved between two points in project's timeline, what types of problems they were, are they important to inform the users about, what issues solved them etc.
+
+Wouldn't it be great to get fantastic release notes compiled for you automaticaly based on all the hard work you put into your GitHub issues and pull requests.
+
+## OK, what can `gren` do for me?
+
+`gren` is a small helpful robot that will do for you just that! To put simply, it can create a release from a tag and compile the release notes using issues or commits.
+
+It also can generate a `CHANGELOG.md` file based on the release notes (or generate a brand new).
+
+## The Concept
+
+The main motivation for bringing `gren` to life was the need for auto generating release notes for every tag in a project.
+The process, [as explained here](https://help.github.com/articles/creating-releases/), requires to go to your project's releases page in GitHub, draft that tag as a new release and manually add what I remembered has changed.
+
+Let `gren` take care of that for you. It automates this process and also writes release notes for you, creating something like this:
+
+> ## v0.6.0 (14/03/2017)
+> 
+> #### Framework Enhancements:
+> 
+> - [#32](https://github.com/github-tools/github-release-notes/issues/32) Unwrap github-api promises
+> - [#26](https://github.com/github-tools/github-release-notes/issues/26) Use external config file
+> - [#23](https://github.com/github-tools/github-release-notes/issues/23) Introduce templates for the issues
+> - [#19](https://github.com/github-tools/github-release-notes/issues/19) Add an "ignore label" flag
+> - [#12](https://github.com/github-tools/github-release-notes/issues/12) Add the chance to rebuild the history of release notes
+> 
+> #### Bug Fixes:
+> 
+> - [#29](https://github.com/github-tools/github-release-notes/issues/29) Remove escaping character on regex
+> - [#24](https://github.com/github-tools/github-release-notes/issues/24) The changelog action doesn't compile latest release
+
+_(yes, this is one of_ 🤖 _'s actual releases)_
+
+## Feed `gren` 🤖
+
+Where is the data coming from? There are two options:
+
+### `issues` (⭐)
+
+If you manage your project with issues, that's where all the information about a change are.
+Issue labels increase the level of depth of what the release notes should show, helping `gren` to group the notes.
+
+_e.g. if you see the example above, the issues are grouped by the two labels `enhancement` and `bug`, then customised via a config file._
+
+`gren` generates those notes by collecting all the issues closed between a tag (defaults to latest) and the tag before it (or a tag that you specify).
+If you want to be more accurate on the issues that belong to a release, you can group them in [milestones](https://github-tools.github.io/github-release-notes/examples.html#milestones) and use only the issues that belong to that Milestone.
+
+> The output above is a result of release notes built from issues.
+
+#### Help 🤖 to write wondeful stuff (issues)
+
+In order to have spliendid generated release notes, we reccomend to follow these convensions:
+
+1. Start the title with a verb (e.g. Change header styles)
+2. Use the imperative mood in the title (e.g. Fix, not Fixed or Fixes header styles)
+3. Use labels wisely and assign one label per issue. `gren` has the [option to ignore issues](#) _(alex: put link to options)_ that have a specified issues.
+
+### `commits`
+
+The simplest way of getting data is from the commits you write.
+Even though it doesn't require a machine-readable commit, still would be better to have them in a nice format.
+
+The output would then use commit messages (title + description) to look something like:
+
+> ## v0.9.0 (17/05/2017)
+> 
+> - Filter milestones (#75)
+>     * Create milestones data-source option
+>     * Add documentation for the milestones option
+> - Support GitHub enterprise (#73)
+>     * Support GitHub enterprise
+>     * Add api-url to options documentation
+> - Update CHANGELOG.md
+
+#### Help 🤖 to write wondeful stuff (commits)
+
+In order to have spliendid generated release notes, we reccomend to follow these convensions:
+
+1. Start the subject line with a verb (e.g. Change header styles)
+2. Use the imperative mood in the subject line (e.g. Fix, not Fixed or Fixes header styles)
+3. Limit the subject line to about 50 characters
+4. Do not end the subject line with a period
+5. Separate subject from body with a blank line
+6. Wrap the body at 72 characters
+7. Use the body to explain _what_ and _why_ not _how_

docs/css/main.scss

@@ -4,7 +4,7 @@
 
 // Our variables
 $base-font-family: 'PT Sans', Helvetica, Arial, sans-serif;
-$base-font-size:   16px;
+$base-font-size:   18px;
 $small-font-size:  $base-font-size * 0.895;
 $large-font-size:  $base-font-size * 1.40;
 
@@ -21,9 +21,9 @@ $grey-color-light: lighten($grey-color, 30%);
 $grey-color-dark:  darken($grey-color, 25%);
 
 // Width of the content area
-$content-width:    700px;
-$on-palm:          700px;
-$on-laptop:        700px;
+$content-width:    1000px;
+$on-palm:          480px;
+$on-laptop:        800px;