Merge pull request #1151 from chef/dr/www-docs

add docs to the website

docs/inspec_and_friends.md

@@ -4,6 +4,9 @@ title: InSpec and friends
 
 # InSpec and friends
 
+This page looks at projects that are similar to InSpec to explain how they
+relate to each other.
+
 ## RSpec
 
 RSpec is an awesome framework that is widely used to test Ruby code. It
@@ -37,7 +40,7 @@ control "sshd-11" do
 end
 ```
 
-## Serverspec
+## Serverspec
 
 Serverspec can be credited as the first extension of RSpec that enabled
 users to run RSpec tests on servers to verify deployed artifacts. It was

tasks/docs.rb

@@ -194,22 +194,21 @@ namespace :docs do
   end
 
   desc 'Create resources docs'
-  task :resources do
+  task :resources, [:clean] do
     src = 'docs'
-    dst = 'www/source/docs/resources'
+    dst = 'www/source/docs/reference/resources'
+    FileUtils.mkdir_p(dst)
+
     docs = ResourceDocs.new(src)
     resources = Dir[File.join(src, 'resources/*.md.erb')]
                 .map { |x| x.sub(/^#{src}/, '') }
     puts "Found #{src.length} resource docs"
-    puts "Clean up #{dst}"
-    FileUtils.rm_rf(dst) if File.exist?(dst)
-    FileUtils.mkdir_p(dst)
     puts "Rendering docs to #{dst}/"
 
     progressbar = ProgressBar.create(total: resources.length, title: 'Rendering')
     resources.each do |file|
-      progressbar.log('    '+file)
+      progressbar.log('          '+file)
-      dst_name = File.basename(file).sub(/\.erb$/, '')
+      dst_name = File.basename(file).sub(/\.md\.erb$/, '.html.md')
       res = docs.render(file)
       File.write(File.join(dst, dst_name), res)
       progressbar.increment
@@ -223,13 +222,36 @@ namespace :docs do
     list = ''
     resources.each do |file|
       name = File.basename(file).sub(/\.md\.erb$/, '')
-      list << f.li(f.a(name, name + '.html'))
+      list << f.li(f.a(name, 'resources/' + name + '.html'))
     end
     res << f.ul(list)
     dst = File.join(src, 'resources.md')
     puts "Create #{dst}"
     File.write(dst, res)
+  end
 
+  desc 'Clean all rendered docs from www/'
+  task :clean do
+    dst = 'www/source/docs/reference'
+    puts "Clean up #{dst}"
+    FileUtils.rm_rf(dst) if File.exist?(dst)
+    FileUtils.mkdir_p(dst)
+  end
+
+  desc 'Copy fixed doc files'
+  task copy: [:clean, :resources] do
+    src = 'docs'
+    dst = 'www/source/docs/reference'
+    files = Dir[File.join(src, '*.md')]
+
+    progressbar = ProgressBar.create(total: files.length, title: 'Copying')
+    files.each do |path|
+      name = File.basename(path).sub(/\.md$/, '.html.md')
+      progressbar.log('          '+File.join(dst, name))
+      FileUtils.cp(path, File.join(dst, name))
+      progressbar.increment
+    end
+    progressbar.finish
   end
 end
 

www/.gitignore

@@ -18,4 +18,4 @@
 .DS_Store
 
 # Ignore rendered files from docs/
-source/docs/resources/
+source/docs/reference/

www/Gemfile

@@ -17,3 +17,5 @@ gem 'middleman-compass', '>= 4.0.0'
 gem 'middleman', '>= 4.0.0'
 gem 'middleman-livereload'
 gem 'middleman-autoprefixer'
+gem 'middleman-syntax'
+gem 'redcarpet'

www/Gemfile.lock

@@ -100,6 +100,9 @@ GEM
     middleman-sprockets (4.0.0)
       middleman-core (~> 4.0)
       sprockets (>= 3.0)
+    middleman-syntax (3.0.0)
+      middleman-core (>= 3.2)
+      rouge (~> 2.0)
     minitest (5.9.0)
     multi_json (1.12.1)
     padrino-helpers (0.13.3.2)
@@ -115,6 +118,8 @@ GEM
     rb-fsevent (0.9.7)
     rb-inotify (0.9.7)
       ffi (>= 0.5.0)
+    redcarpet (3.3.4)
+    rouge (2.0.6)
     sass (3.4.22)
     servolux (0.12.0)
     slim (3.0.7)
@@ -141,6 +146,8 @@ DEPENDENCIES
   middleman-compass (>= 4.0.0)
   middleman-livereload
   middleman-sprockets (>= 4.0.0)
+  middleman-syntax
+  redcarpet
   slim (>= 3.0)
   tzinfo-data
   wdm (~> 0.1.0)

www/config.rb

@@ -12,8 +12,8 @@ page '/*.xml', layout: false
 page '/*.json', layout: false
 page '/*.txt', layout: false
 
-# With alternative layout
+# With alternative layout: we send the sidebar request to the default layout
-# page 'docs/*', layout: :sidebar, locals: { sidebar_layout: 'docs' }
+page 'docs/*', layout: :layout, locals: { sidebar_layout: 'docs' }
 
 # Proxy pages (http://middlemanapp.com/basics/dynamic-pages/)
 # proxy '/this-page-has-no-template.html', '/template-file.html', locals: {
@@ -28,6 +28,10 @@ configure :development do
   activate :livereload
 end
 
+# Methods defined in the helpers block are available in templates
+require 'lib/sidebar_helpers'
+helpers SidebarHelpers
+
 # Methods defined in the helpers block are available in templates
 # helpers do
 #   def some_helper
@@ -47,6 +51,7 @@ end
 activate :sprockets
 activate :autoprefixer
 activate :directory_indexes
+activate :syntax
 set :trailing_slash, false
-set :markdown_engine, :kramdown
+set :markdown_engine, :redcarpet
-set :markdown, coderay_line_numbers: :table
+set :markdown, fenced_code_blocks: true, smartypants: true, coderay_line_numbers: :table

www/data/docs_sidebar.yml

@@ -3,9 +3,9 @@ sidebar_links:
 - title: Getting Started
   links:
   - title: Overview
-    link: "/docs/reference/overview.html"
+    link: "/docs"
   - title: Get InSpec
-    link: "/under_construction"
+    link: "https://downloads.chef.io/inspec"
   - title: Tutorials
     link: "/docs/tutorials.html"
   - title: InSpec and friends
@@ -30,7 +30,3 @@ sidebar_links:
     link: "/docs/reference/shell.html"
   - title: Ruby usage
     link: "/docs/reference/ruby_usage.html"
-- title: Contribute
-  links:
-  - title: Help build InSpec
-    link: "/community"

www/lib/sidebar_helpers.rb

@@ -0,0 +1,46 @@
+# encoding: utf-8
+# helper methods for source/layouts/sidebar.slim
+module SidebarHelpers
+  SIDEBAR_LAYOUTS = %w{docs}.freeze
+
+  def sidebar_data(sidebar_layout)
+    unless SIDEBAR_LAYOUTS.include?(sidebar_layout)
+      fail "'#{sidebar_layout}' is not a valid sidebar layout type."
+    end
+
+    data.public_send(:"#{sidebar_layout}_sidebar").sidebar_links.dup
+  end
+
+  def link_classes(current_url, item_link)
+    'is-active' if same_link?(current_url, item_link.link)
+  end
+
+  def print_sub_links?(current_url, item_link)
+    return false unless sub_links?(item_link)
+
+    same_link?(item_link.link, current_url) ||
+      active_child?(current_url, item_link)
+  end
+
+  def same_link?(one, two)
+    strip_trailing_slash(one) == strip_trailing_slash(two)
+  end
+
+  def strip_trailing_slash(str)
+    str.end_with?('/') ? str[0..-2] : str
+  end
+
+  def active_child?(current_url, item_link)
+    return false unless sub_links?(item_link)
+
+    sub_link_urls(item_link).include?(strip_trailing_slash(current_url))
+  end
+
+  def sub_links?(item_link)
+    item_link.respond_to?(:sub_links) && item_link.sub_links.count > 0
+  end
+
+  def sub_link_urls(item)
+    item.sub_links.collect { |sub| strip_trailing_slash(sub.link) }
+  end
+end

www/source/docs/index.html.md

@@ -1,20 +0,0 @@
-# InSpec Documentation
-
-Welcome to the InSpec documentation! This is a reference guide for all available
-features and options.
-
-## Are you new to InSpec?
-
-If you're just getting started and want a quick introduction, then we recommend
-you start with the following items in the order listed.
-
-<div class="row">
-  <div class="columns medium-6">
-    <a class="button" href="under_construction.html" target="_blank">Try InSpec demo</a>
-    Complete a short interactive demo
-  </div>
-  <div class="columns medium-6">
-    <a class="button" href="docs/tutorials.html" target="_blank">Go tutorials</a>
-    Get your first hands-on experience
-  </div>
-</div>

www/source/docs/index.html.slim

@@ -0,0 +1,23 @@
+h1 InSpec Documentation
+
+p Welcome to the InSpec documentation! This is a reference guide for all available features and options.
+
+p In the navigation, you will see 2 sections. The first provides a few links to get started and context around InSpec. The second section contains references to all elements of InSpec: The DSL, CLI, profiles, resources, and matchers.
+
+h2 Are you new to InSpec?
+
+p If you're just getting started and want a quick introduction, then we recommend you start with the following items in the order listed.
+
+.row
+  .columns.medium-6.center
+    a.button.try-demo href="#" Try InSpec demo
+    p Complete a short interactive demo
+  .columns.medium-6.center
+    a.button.try-demo href="docs/tutorials.html" Tutorials
+    p Get your first hands-on experience
+
+h2 Contributing
+
+p This documentation is automatically generated from the InSpec repository and source code.
+
+p To contribute, please have a look at the <a href="https://github.com/chef/inspec/tree/master/docs">docs</a> folder of the project.

www/source/docs/search.html.slim

@@ -0,0 +1,19 @@
+---
+title: Search InSpec Docs
+---
+
+h2 Search the InSpec Documentation
+
+javascript:
+  // TODO: add the inspec search here
+  (function() {
+    var cx = '014746884379529974319:rvxyzhpu2us';
+    var gcse = document.createElement('script');
+    gcse.type = 'text/javascript';
+    gcse.async = true;
+    gcse.src = 'https://cse.google.com/cse.js?cx=' + cx;
+    var s = document.getElementsByTagName('script')[0];
+    s.parentNode.insertBefore(gcse, s);
+  })();
+
+<gcse:search webSearchResultSetSize="20"></gcse:search>

www/source/index.html.slim

@@ -73,6 +73,3 @@ title: InSpec - Audit and Test Framework
             and configurations.
         h3.code-snippet--heading Extensible:
         p.code-snippet--text Easily create custom resources and share them.
-    hr.home-divider
-    h2.main-subhead.text-center The Guiding Principles of InSpec
-    p Lorem ipsum...

www/source/layouts/_nav.slim

@@ -8,34 +8,37 @@ nav#main-nav
     li.main-nav--link-ctas
       a.button.transparent.try-demo href="#" Try the Demo
       a.button.secondary href="https://downloads.chef.io/inspec" Download
-    li.main-nav--link
+    - if locals[:sidebar_layout] == 'docs'
-      a href="/"
+      = partial "layouts/sidebar"
-        i.main-nav--link-icon.fa.fa-home
+    - else
-        span.main-nav--link-text Overview
+      li.main-nav--link
-    li.main-nav--link
+        a href="/"
-      a href="/tutorials"
+          i.main-nav--link-icon.fa.fa-home
-        i.main-nav--link-icon.fa.fa-flask
+          span.main-nav--link-text Overview
-        span.main-nav--link-text Tutorials
+      li.main-nav--link
-    li.main-nav--link
+        a href="/tutorials"
-      a href="/docs"
+          i.main-nav--link-icon.fa.fa-flask
-        i.main-nav--link-icon.fa.fa-file-text-o
+          span.main-nav--link-text Tutorials
-        span.main-nav--link-text Docs
+      li.main-nav--link
-    li.main-nav--link
+        a href="/docs"
-      a href="/community"
+          i.main-nav--link-icon.fa.fa-file-text-o
-        i.main-nav--link-icon.fa.fa-group
+          span.main-nav--link-text Docs
-        span.main-nav--link-text Community
+      li.main-nav--link
-    li.main-nav--link
+        a href="/community"
-      a href="https://downloads.chef.io/inspec"
+          i.main-nav--link-icon.fa.fa-group
-        i.main-nav--link-icon.fa.fa-download
+          span.main-nav--link-text Community
-        span.main-nav--link-text Downloads
+      li.main-nav--link
-    li.main-nav--link
+        a href="https://downloads.chef.io/inspec"
-      a href="https://github.com/chef/inspec"
+          i.main-nav--link-icon.fa.fa-download
-        i.main-nav--link-icon.fa.fa-github
+          span.main-nav--link-text Downloads
-        span.main-nav--link-text Github Project
+      li.main-nav--link
-    li.main-nav--link
+        a href="https://github.com/chef/inspec"
-      a href="https://github.com/chef/inspec/blob/master/CONTRIBUTING.md"
+          i.main-nav--link-icon.fa.fa-github
-        i.main-nav--link-icon.fa.fa-code-fork
+          span.main-nav--link-text Github Project
-        span.main-nav--link-text Contribute
+      li.main-nav--link
+        a href="https://github.com/chef/inspec/blob/master/CONTRIBUTING.md"
+          i.main-nav--link-icon.fa.fa-code-fork
+          span.main-nav--link-text Contribute
 
 nav#main-nav-ctas
   a.button.transparent.try-demo href="#" Try the Demo

www/source/layouts/_sidebar.slim

@@ -0,0 +1,19 @@
+.container__has-sidebar
+  .row
+    .main-sidebar
+        - if locals[:sidebar_layout] == 'docs'
+          form.main-sidebar--search action="/docs/search/" method="get"
+            input type="text" placeholder="Search Documentation" name="q"
+        ul.main-sidebar--links
+          - sidebar_data(sidebar_layout).each do |item|
+            li.main-sidebar--link
+              h6 = item.title
+              ul.main-sidebar--list.no-bullet
+                - item.links.each do |item_link|
+                  li.main-sidebar--list--item class=link_classes(current_resource.url, item_link)
+                    = link_to item_link.title, item_link.link
+                    - if print_sub_links?(current_resource.url, item_link)
+                      ul.main-sidebar--list--item--dropdown.no-bullet
+                        - item_link.sub_links.each do |sub_link|
+                          li.main-sidebar--list--item  class=link_classes(current_resource.url, sub_link)
+                            = link_to sub_link.title, sub_link.link

www/source/stylesheets/_sidebar.scss

@@ -0,0 +1,66 @@
+.main-sidebar ul {
+  list-style: none;
+  margin-left: 0.5rem;
+  ul {
+    margin-left: 0;
+    margin-bottom: 1rem;
+  }
+}
+
+.main-sidebar--link h6 {
+  font-weight: 500;
+
+}
+
+.main-sidebar--list--item {
+  position: relative;
+  padding: 3px 0;
+  text-transform: uppercase;
+  font-size: 14px;
+
+  & > a {
+    color: $inspec-grey;
+
+    &:hover,
+    &:focus,
+    &:active {
+      color: darken($inspec-grey, 15%);
+    }
+  }
+}
+
+.center {
+  text-align: center;
+}
+
+.gsc-adBlock, .gcsc-branding {
+  display: none !important;
+}
+
+.gsc-control-cse {
+  padding: 0 !important;
+
+  tbody {
+    border: none;
+    background: none;
+  }
+
+  .gsc-input-box {
+    height: 3rem;
+    table {
+      margin-bottom: 0;
+    }
+  }
+
+  .gsc-input input {
+    box-shadow: none !important;
+  }
+
+  .gsc-search-button {
+    font-family: inherit;
+    font-size: 11px;
+    padding: 5px 18px;
+    height: 27px;
+    min-width: 54px;
+  }
+}

www/source/stylesheets/site.css.scss

@@ -4,6 +4,7 @@
 @import "settings";
 @import "buttons";
 @import "nav";
+@import "sidebar";
 @import "footer";
 @import "layout";
 @import "typography";