Class: ApiGuides::Generator

Inherits:
Object
  • Object
show all
Extended by:
ActiveSupport::Memoizable
Defined in:
lib/api_guides/generator.rb

Overview

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](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. = "/path/to/logo.png"

# whatever else you need to do

generator.generate

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(attributes = {}) ⇒ Generator

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.



68
69
70
71
72
 
# File 'lib/api_guides/generator.rb', line 68

def initialize(attributes = {})
  attributes.each_pair do |attribute, value|
    self.send("#{attribute}=", value)
  end
end

Instance Attribute Details

#default ⇒ Object

Returns the value of attribute default.



57
58
59
 
# File 'lib/api_guides/generator.rb', line 57

def default
  @default
end

#logo ⇒ Object

Returns the value of attribute logo.



57
58
59
 
# File 'lib/api_guides/generator.rb', line 57

def 
  @logo
end

#site_path ⇒ Object

Returns the value of attribute site_path.



57
58
59
 
# File 'lib/api_guides/generator.rb', line 57

def site_path
  @site_path
end

#source_path ⇒ Object

Returns the value of attribute source_path.



57
58
59
 
# File 'lib/api_guides/generator.rb', line 57

def source_path
  @source_path
end

#title ⇒ Object

Returns the value of attribute title.



57
58
59
 
# File 'lib/api_guides/generator.rb', line 57

def title
  @title
end

Instance Method Details

#generate ⇒ Object

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`.



83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'lib/api_guides/generator.rb', line 83

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. = File.basename  if 
      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. = File.basename  if 
    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 "#{}", "#{site_path}/#{File.basename()}" if 

  # 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