generate docs for cli

docs/README.md

@@ -6,7 +6,27 @@ The goal of this folder is for any community member to clone these docs, make th
 
 ## How to build docs
 
-TODO
+We build docs by:
+
+1. Auto-generating docs from code
+2. Transforming markdown+snippets in this folder into pure markdown in `www/source/docs`
+3. Rendering them to the website via instructions in `www/`
+
+For development, you **only need step 1**!
+
+**1 Generate docs**
+
+To generate all docs run:
+
+```
+bundle exec rake docs
+```
+
+You can run tasks individually. For a list of tasks run:
+
+```
+bundle exec rake --tasks docs
+```
 
 ## Stability Index
 

tasks/docs.rb

@@ -106,7 +106,7 @@ end
 namespace :docs do
   desc 'Create cli docs'
   task :cli do
-    f = RST
+    f = Markdown
     res = f.meta(title: 'About the InSpec CLI')
     res << f.h1('InSpec CLI')
     res << f.p('Use the InSpec CLI to run tests and audits against targets '\
@@ -150,3 +150,17 @@ namespace :docs do
     puts "Documentation generated in #{dst.inspect}"
   end
 end
+
+def run_tasks_in_namespace(ns)
+  Rake.application.in_namespace(ns) do |x|
+    x.tasks.each do |task|
+      puts "----> #{task}"
+      task.invoke
+    end
+  end
+end
+
+desc 'Create all docs in docs/ from source code'
+task :docs do
+  run_tasks_in_namespace :docs
+end