Class: ApiGuides::Document
- Inherits:
-
Object
- Object
- ApiGuides::Document
- Extended by:
- ActiveSupport::Memoizable
- Defined in:
- lib/api_guides/document.rb
Overview
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](github.github.com/github-flavored-markdown/). Code is highlighted using [pygments](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.
Instance Attribute Summary collapse
-
#position ⇒ Object
Returns the value of attribute position.
-
#sections ⇒ Object
Returns the value of attribute sections.
-
#title ⇒ Object
Returns the value of attribute title.
Class Method Summary collapse
-
.from_xml(xml) ⇒ Object
Takes XML and parses into into a Document instance.
Instance Method Summary collapse
-
#initialize(attributes = {}) ⇒ Document
constructor
A new instance of Document.
Constructor Details
#initialize(attributes = {}) ⇒ Document
Returns a new instance of Document.
92 93 94 95 96 |
# File 'lib/api_guides/document.rb', line 92 def initialize(attributes = {}) attributes.each_pair do |attr, value| send "#{attr}=", value end end |
Instance Attribute Details
#position ⇒ Object
Returns the value of attribute position.
90 91 92 |
# File 'lib/api_guides/document.rb', line 90 def position @position end |
#sections ⇒ Object
Returns the value of attribute sections.
90 91 92 |
# File 'lib/api_guides/document.rb', line 90 def sections @sections end |
#title ⇒ Object
Returns the value of attribute title.
90 91 92 |
# File 'lib/api_guides/document.rb', line 90 def title @title end |
Class Method Details
.from_xml(xml) ⇒ Object
Takes XML and parses into into a Document instance. It wil also parse the section using its ‘from_xml` method.
101 102 103 104 105 106 107 108 109 |
# File 'lib/api_guides/document.rb', line 101 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 |