api_guides 0.1.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'http://rubygems.org'
+
+# Specify your gem's dependencies in api_guides.gemspec
+gemspec

data/Rakefile

@@ -0,0 +1,11 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+  spec.rspec_opts = ['-c']
+end
+
+task :default => :spec

data/api_guides.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/api_guides/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Adam Hawkins"]
+  gem.email         = ["me@broadcastingadam.com"]
+  gem.description   = %q{Generate HTML documentation for your program with markdown and examples for different languages.}
+  gem.summary       = %q{}
+  gem.homepage      = "https://github.com/threadedlabs/api_guides"
+
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.name          = "api_guides"
+  gem.require_paths = ["lib"]
+  gem.version       = ApiGuides::VERSION
+
+  gem.add_dependency 'mustache'
+  gem.add_dependency 'redcarpet', '~> 2.0'
+  gem.add_dependency 'nokogiri'
+  gem.add_dependency 'activesupport', '~> 3.0'
+  gem.add_dependency 'i18n'
+
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'simplecov'
+end

data/lib/api_guides.rb

@@ -0,0 +1,22 @@
+# -*- encoding: utf-8 -*-
+
+require "nokogiri"
+require "mustache"
+require "i18n"
+require "active_support/core_ext/string"
+require "api_guides/version"
+require "api_guides/markdown_helper"
+require "api_guides/view_helper"
+require "api_guides/document"
+require "api_guides/example"
+require "api_guides/reference"
+require "api_guides/generator"
+require "api_guides/section"
+require "api_guides/views/page"
+require "api_guides/views/document"
+require "api_guides/views/section"
+require "api_guides/views/example"
+require "api_guides/views/reference"
+
+module ApiGuides
+end

data/lib/api_guides/document.rb

@@ -0,0 +1,111 @@
+# -*- encoding: utf-8 -*-
+
+require 'active_support/core_ext/object'
+
+module ApiGuides
+  # The document class models the raw information in each guide.
+  #
+  # The document is parsed according to this format:
+  #
+  #     <document>
+  #       <title>Top Level Header</title>
+  #       <position>1<>
+  #       <section title="Level Two Header">
+  #         <docs>
+  #           Insert your markdown here
+  #         </docs>
+  #         <reference title="Example1">
+  #           A Reference element will always be shown with the associated section.
+  #           You should use this area to provide technical documentation
+  #           for each section. You could use the <docs>'s element to
+  #           describe how each thing works, and use the reference to show
+  #           a method signature with return values.
+  #
+  #           Write your reference with markdown.
+  #
+  #           You can use standard markdown syntax plus 
+  #           helpers added by this library
+  #         </reference>
+  #         <examples>
+  #           <example language="ruby"><![CDATA[
+  #             Insert your markdown here.
+  #
+  #             You can use github fenced codeblocks to create syntax 
+  #             highlighting like this:
+  #
+  #             ```ruby
+  #             # note you don't have to indent!
+  #             def method_name(arg)
+  #               # do stuff
+  #             end
+  #             ```
+  #
+  #             You can also specify code like you would in normal markdown
+  #             by indenting by 2 tabs or 4 spaces:
+  #
+  #                 // here is an example data structure
+  #                 {
+  #                   "foo": "bar"
+  #                 }
+  #
+  #             **Note!** All content will be automatically left 
+  #             aligned so you can indent your markup to make 
+  #             it easier to read. 
+  #           ]]></example>
+  #           <example language="javascript"><![CDATA[
+  #             Insert more markdown here
+  #           ]]></example>
+  #         </examples>
+  #       </section>
+  #     </document>
+  #
+  #
+  #  **Important**: Be sure to wrap your text tags with `<![CDATA[ ]]>` otherwise
+  #  the file may not parse correctly since it may not be valid XML.
+  #
+  # `title` element names this section of the guide.
+  #
+  # `position` element determines the order to render the document. 
+  # This allows you to have multiple documents in any structure you want.
+  #
+  # You can have has many sections as you want. You should only have one 
+  # <doc> block. You can have have <examples> if you want. There can be
+  # as many <example>'s inside if you want. Another copy of the site will
+  # be generated for each language. 
+  #
+  # The markdown is parsed [Github Markdown](http://github.github.com/github-flavored-markdown/).
+  # Code is highlighted using [pygments](http://pygments.org/).
+  #
+  # This class parses the table of contents for each document into a TableOfContents instance.
+  # It also parses an array of Section instances. The Generator uses this information
+  # to generate the final files.
+  #
+  # You may choose to indent your tags or not. All content will be
+  # left-aligned so code and other indentation senstive markdown will be
+  # parsed correctly.
+  class Document
+    # Use ActiveSupport to memoize parsing methods
+    extend ActiveSupport::Memoizable
+
+    attr_accessor :title, :position, :sections
+
+    def initialize(attributes = {})
+      attributes.each_pair do |attr, value|
+        send "#{attr}=", value
+      end
+    end
+
+    # Takes XML and parses into into a Document
+    # instance. It wil also parse the section
+    # using its `from_xml` method.
+    def self.from_xml(xml)
+      doc = Nokogiri::XML.parse(xml).at_xpath('//document')
+      document = Document.new :title => doc.at_xpath('./title').try(:content), 
+        :position => doc.at_xpath('./position').try(:content).try(:to_i)
+
+      document.sections = doc.xpath('//section').map {|section_xml| Section.from_xml(section_xml.to_s) }
+
+      document
+    end
+  end
+end

data/lib/api_guides/example.rb

@@ -0,0 +1,38 @@
+# -*- encoding: utf-8 -*-
+
+module ApiGuides
+  # This class models an example for your documentation.
+  # It is for a specific language and contains a raw
+  # markdown formatted string. A diffrent version of the documentation
+  # will be generated for each language with examples.
+  #
+  # You never interact with this class directly.
+  class Example
+    attr_accessor :language
+    attr_accessor :content
+
+    def initialize(attributes = {})
+      attributes.each_pair do |attr, value|
+        send "#{attr}=", value
+      end
+    end
+
+    # Takes an XML representation and parse
+    # it into an Example instance. 
+    # 
+    # Here is XML format expected:
+    #
+    #     <examle language="Foo">
+    #       <![CDATA[
+    #       Insert your markdown here
+    #       ]]>
+    #     </reference>
+    #
+    # This would set `#language` to 'Foo'
+    # and #content to 'Insert your markdown here'
+    def self.from_xml(xml)
+      doc = Nokogiri::XML.parse(xml).at_xpath('//example')
+      Example.new :language => doc.attributes['language'].try(:value), :content => doc.content
+    end
+  end
+end

data/lib/api_guides/generator.rb

@@ -0,0 +1,161 @@
+# -*- encoding: utf-8 -*-
+
+require 'fileutils'
+
+module ApiGuides
+  # The generator creates a static html document for each different
+  # language you have examples for. You only ever interact
+  # with the Generator. It scans the specified directory for XML
+  # files and parses them into Documents. It then uses the documents
+  # to create the HTML file.
+  #
+  # The output is directly inspired by [Stripe](https://stripe.com/docs/api)
+  # (which is Docco inspired). We mix it with a hint of Twitter bootstrap
+  # and *poof!* We have documentation.
+  #
+  # The Generator only needs to know 4 things.
+  #
+  # 1. The absolute path to the folder containing all the XML files.
+  # 2. The absolute path to the folder to generate the static site.
+  # 3. What language is the default aka which languages go in `index.html`.
+  # 4. The site title. This goes in the `<title>` and the top nav bar.
+  #
+  # You may also configure the generator with a logo which will be copied
+  # into the site directory.
+  #
+  # The generator creates a static site following this structure:
+  #
+  #     /
+  #     |- sytle.css
+  #     |- logo.png
+  #     |- index.html
+  #     |- ruby.html
+  #     |- phython.html
+  #     |- objective_c.html
+  #
+  # Once you have the site you can use any webserver you want to serve it up!
+  #
+  # You can refer to Readme for an example of serving it for free with heroku.
+  #
+  # You can instantiate a new Generator without any arguments.
+  # You should assign the individual configuration options via
+  # the accessors. Here is an example:
+  #
+  #     generator = ApiGuides::Generator.new
+  #     generator.source_path = "/path/to/guides/folder"
+  #     generator.site_path = "/path/to/site/folder"
+  #     generator.default = "json"
+  #     generator.title = "Slick API docs"
+  #     generator.logo = "/path/to/logo.png"
+  #
+  #     # whatever else you need to do
+  #
+  #     generator.generate
+  class Generator
+    extend ActiveSupport::Memoizable
+
+    attr_accessor :source_path, :site_path, :default, :title, :logo
+
+    # You can instatiate a new generator by passing a hash of attributes
+    # and values. 
+    #
+    #     Generator.new({
+    #       :source_path => File.dir_name(__FILE__) + "/guides"
+    #       :site_path => File.dir_name(__FILE__) + "/source"
+    #     })
+    #
+    # You can also omit the hash if you like.
+    def initialize(attributes = {})
+      attributes.each_pair do |attribute, value|
+        self.send("#{attribute}=", value)
+      end
+    end
+
+    # Parse all the documents and generate the different HTML files.
+    #
+    # This method will remove `source_path/*` and `site_path/*` to
+    # ensure that a clean site is generated each time.
+    #
+    # It reads all the xml documents according to `source_path/**/*.xml` 
+    # and uses them to create the HTML.
+    #
+    # Documents are rendered in the order specified `#position`.
+    def generate
+      # Ensure site is a directory
+      FileUtils.mkdir_p site_path
+
+      # If there is more than one language, then we need to create
+      # multiple files, one for each language.
+      if languages.size >= 1
+
+        # Enter the most dastardly loop. 
+        # Create a View::Document with sections only containing the 
+        # specified language. 
+        languages.map do |language|
+          document_views = documents.map do |document|
+            document.sections = document.sections.map do |section|
+              section.examples = section.examples.select {|ex| ex.language.blank? || ex.language == language }
+              section
+            end
+
+            Views::Document.new document
+          end
+
+          # Use Mustache to create the file
+          page = Page.new
+          page.title = title
+          page.logo = File.basename logo if logo
+          page.documents = document_views
+
+          File.open("#{site_path}/#{language.underscore}.html", "w") do |file|
+            file.puts page.render
+          end
+        end
+
+        # copy the default language to the index and were done!
+        FileUtils.cp "#{site_path}/#{default.underscore}.html", "#{site_path}/index.html"
+
+      # There are no languages specified, so we can just create one page
+      # using a collection of Document::View.
+      else 
+        document_views = documents.map do |document|
+          Views::Document.new document
+        end
+
+        page = Page.new
+        page.title = title
+        page.logo = File.basename logo if logo
+        page.documents = document_views
+
+        File.open("#{site_path}/index.html", "w") do |file|
+          file.puts page.render
+        end
+      end
+
+      # Copy the logo if specified
+      FileUtils.cp "#{logo}", "#{site_path}/#{File.basename(logo)}" if logo
+
+      # Copy all the stylesheets into the static directory and that's it!
+      resources_path = File.expand_path "../resources", __FILE__
+
+      FileUtils.cp "#{resources_path}/style.css", "#{site_path}/style.css"
+      FileUtils.cp "#{resources_path}/syntax.css", "#{site_path}/syntax.css"
+    end
+
+    private
+    # Parse and sort all the documents specified recusively in the `source_path`
+    def documents
+      Dir["#{source_path}/**/*.xml"].map do |path|
+        Document.from_xml File.read(path)
+      end.sort {|d1, d2| d1.position <=> d2.position }
+    end
+
+    # Loop all the document's sections and examples to see all the different
+    # languages specified by this document.
+    def languages
+      documents.collect(&:sections).flatten.collect(&:examples).flatten.map(&:language).compact.uniq
+    end
+    # Store this calculation for later so we don't have to do this retarded loop again.
+    memoize :languages
+  end
+end

data/lib/api_guides/markdown_helper.rb

@@ -0,0 +1,59 @@
+# -*- encoding: utf-8 -*-
+
+require 'redcarpet'
+require 'net/http'
+
+module ApiGuides
+  module MarkdownHelper
+    class HTMLwithHighlighting < ::Redcarpet::Render::HTML
+      # Override the default so we can do syntax highlighting
+      # based on the language
+      def bblock_code(code, language)
+        # If there's a language, use the pygments webservice
+        # to highlight for the language
+        if language
+          Net::HTTP.post_form(
+            URI.parse('http://pygments.appspot.com/'),
+            {'lang' => language, 'code' => code}
+          ).body
+        else
+         %Q{<code class="#{language}"><pre>#{code}></pre></code>}
+        end
+      end
+    end
+
+    # Simple helper to convert a string to markdown using
+    # all our custom hax (including syntax highligting).
+    # It uses Redcarpert to do the heavy lifting.
+    def markdown(string)
+      content = left_align string
+
+      md = ::Redcarpet::Markdown.new HTMLwithHighlighting, :auto_link => true, 
+        :no_intra_emphis => true,
+        :tables => true, 
+        :fenced_code_blocks => true,
+        :strikethrough => true
+
+      md.render content
+    end
+
+    # Takes a string and removes trailing whitespace from the
+    # beginning of each line. It takes the number of leading whitespace
+    # characters from the first line and removes that from every single
+    # line in the string. It's used to normalize strings that may be
+    # intended when writing the XML documents.
+    def left_align(string)
+      return string unless string.match(/^(\s+)\S/)
+
+      lines = string.gsub("\t", "  ").lines
+
+      first_line = lines.select {|l| l.present?}.first
+
+      leading_white_space = first_line.match(/^(\s+)\S/)[1].length
+
+      aligned_string = lines.map do |line|
+        line.gsub(/^\s{#{leading_white_space}}/, '')
+      end.join('')
+    end
+  end
+end