Permalink
Browse files

Updated .gitignore, added API docs (prelim.) + HTML generation script…

…, corrected typo?
  • Loading branch information...
1 parent b727004 commit 15a3cb90bdcab9b7fd319e0b98531d55322f787c @lucjon committed Jun 14, 2011
Showing with 386 additions and 4 deletions.
  1. +2 −1 .gitignore
  2. +247 −0 api.yml
  3. +134 −0 makedoc.py
  4. +3 −3 stackexchange/__init__.py
View
@@ -6,4 +6,5 @@ __pycache__
*~
dist/*
build/*
-*.egg-info
+*.egg-info
+api.html
View
247 api.yml
@@ -0,0 +1,247 @@
+answers:
+ answers:
+ se_route: /answers
+ description: Get all answers on the site.
+
+ function: Site.answers
+ returns: ResultSet <Answer>
+
+ answers_id:
+ se_route: /answers/{id}
+ description: Get the answer identified by the specified ID.
+
+ function: Site.answer
+ parameters:
+ id: The ID of the specified answer.
+ returns: Answer
+
+ answers_ids:
+ se_route: /answers/{ids}
+ description: Get the answers identified by the specified IDs.
+
+ function: Site.answers
+ parameters:
+ ids: One or more IDs in a Python iterable.
+ returns: ResultSet <Answer>
+
+ example:
+ so.answers([1, 2, 3])
+
+ answers_comments:
+ se_route: /answers/{ids}/comments
+
+ see: comments.posts_comments
+
+badges:
+ badges:
+ se_route: /badges
+ description: Get all badges on the site, in alphabetical order.
+
+ function: Site.all_badges
+ returns: ResultSet <Badge>
+
+ badges_id:
+ se_route: /badges/{id}
+ description: Get all users who have been awarded the badge specified by ID.
+
+ function: Site.users_with_badge
+ parameters:
+ id: The ID of the badge.
+
+ returns: Badge
+
+ badges_ids:
+ se_route: /badges/{ids}
+ description: Get all users who have been awarded any of the badges specified in IDs.
+
+ function: Site.badges
+ parameters:
+ ids: One or more badge IDs in an iterable.
+
+ returns: ResultSet <Badge>
+
+ badge_by_id:
+ description: Get a badge object for the specified ID.
+
+ function: Site.badge
+ parameters:
+ nid: The ID of the badge.
+
+ returns: Badge
+
+ badge_by_name:
+ description: Get a Badge object for the badge with the specified name.
+
+ function: Site.badge
+ parameters:
+ name: (Keyword parameter) The name of the badge.
+
+ returns: Badge
+
+ badges_non_tag:
+ se_route: /badges/name
+ description: Get all non-tagged-based badges in alphabetical order.
+
+ function: Site.all_nontag_badges
+ returns: ResultSet <Badge>
+
+ badges_tags:
+ se_route: /badges/tags
+ description: Get all tag-based badges.
+
+ function: Site.all_tag_badges
+ returns: ResultSet <Badge>
+
+comments:
+ comments:
+ se_route: /comments
+ description: Get all comments on the site.
+
+ function: Site.comments
+ returns: ResultSet <Comment>
+
+ comments_ids:
+ se_route: /comments/{ids}
+ description: Get comments identified by a set of IDs.
+
+ function: Site.comments
+ parameters:
+ ids: (Keyword parameter) The IDs of the comments to request.
+
+ returns: ResultSet <Comment>
+
+ posts_comments:
+ se_route: /posts/{ids}/comments
+ description: Get comments on the posts (question or answer) identified by a set of IDs.
+
+ function: Site.comments
+ parameters:
+ posts: (Keyword parameter) The IDs of the posts whose comments are to be requested.
+ returns: ResultSet <Comment>
+
+errors:
+ error:
+ se_route: /errors/{id}
+ unimplemented: True
+
+privileges:
+ privileges:
+ se_route: /privileges
+ description: Get all the privileges available on the site.
+
+ function: Site.privileges
+ returns: ResultSet <Privelege>
+
+questions:
+ questions:
+ se_route: /questions
+ description: Get all questions on the site.
+
+ function: Site.questions
+ returns: ResultSet <Question>
+
+ questions_ids:
+ se_route: /questions/{ids}
+ description: Get the questions identified by IDs.
+
+ function: Site.questions
+ parameters:
+ ids: (Keyword parameter) The IDs of the questions to request.
+
+ returns: ResultSet <Question>
+
+ questions_ids_answers:
+ se_route: /questions/{ids}/answers
+ description: Get the answers of the questions identified by IDs.
+
+ unimplemented: True
+
+ questions_comments:
+ se_route: /questions/{ids}/comments
+ description: Get comments on the questions identified by IDs.
+
+ function: Site.comments
+ parameters:
+ posts: (Keyword parameter) The IDs of the questions whose comments to request.
+
+ returns: ResultSet <Comment>
+
+ questions_linked:
+ se_route: /questions/{ids}/linked
+ description: Get the questions that link to the questions identified by a set of IDs.
+
+ function: Site.questions.linked_to
+ parameters:
+ qn: The ID, or a list of IDs, of the question whose linked questions should be retrieved.
+
+ returns: ResultSet <Question>
+
+ questions_related:
+ se_route: /questions/{ids}/related
+ description: Get questions related to the questions specified by IDs.
+
+ function: Site.questions.related_to
+ parameters:
+ qn: The ID, or a list of IDs, of the question whose related questions should be retrieved.
+
+ returns: ResultSet <Question>
+
+ questions_timeline:
+ se_route: /questions/{ids}/timeline
+ description: Get the timelines of the questions identified by IDs.
+
+ unimplemented: True
+
+ questions_unanswered:
+ se_route: /questions/unanswered
+ description: Gets all unanswered questions.
+
+ function: Site.questions.unanswered
+ returns: ResultSet <Question>
+
+ questions_no_answers:
+ se_route: /questions/no-answers
+ description: Get all the questions on the site with no answers.
+
+ function: Site.questions.no_answers
+ returns: ResultSet <Question>
+
+revisions:
+ revisions_post:
+ se_route: /revisions/{id}
+ description: Get all revisions for the post with the specified ID.
+
+ function: Site.revisions
+ parameters:
+ post: The post or post ID whose revisions are to be requested.
+ returns: ResultSet <Revision>
+
+ revision:
+ se_route: /revisions/{id}/{revision-guid}
+ description: Get a specific revision identified by a post ID a revision GUID.
+
+ function: Site.revision
+ parameters:
+ post: The post or post ID whose revisions are to be requested.
+ guid: The GUID of the specific revision to request.
+
+search:
+ search:
+ se_route: /search
+ description: Search the site.
+
+ parameters:
+
+
+
+__style__: |
+ h1, h2, h3, h4 { font-family: Palatino, Palatino Linotype, TeXGyrePagella, serif; }
+ body { font-family: Gill Sans, GillSans, Gill Sans MT, Arial, Helvetica, sans-serif; }
+ .description { font-size: 1.1em; }
+ .prototype, .returns span, .example { font-family: Monaco, Consolas, monospace; background-color: #EEE; padding: 4px; margin: 3px; }
+ .api { text-indent: 2em; }
+ .param_name { font-style: italic; padding-right: 10px; }
+ .returns { font-weight: bold; }
+ .returns span { font-weight: normal; }
+ .example, .params { text-indent: 3.5em; }
+ .see { font-style: italic; }
View
@@ -0,0 +1,134 @@
+#!/usr/bin/env python
+# Creates HTML documentation from api.yml
+
+import yaml
+
+class Function(object):
+ def __init__(self, id, tree_ob):
+ def use(key, v=None):
+ if key in tree_ob:
+ val = tree_ob[key]
+
+ if isinstance(val, str):
+ val = val.replace('<', '&lt;').replace('>', '&gt;')
+
+ setattr(self, key, val)
+ return True
+ else:
+ if v is not None:
+ setattr(self, key, v)
+ return False
+
+ self.id = id
+
+ use('description', '')
+ use('se_route', self.description)
+
+ if not use('unimplemented', False):
+ use('function')
+ use('returns')
+ use('parameters')
+ use('see')
+ use('example')
+
+ @property
+ def prototype(self):
+ if self.unimplemented:
+ raise AttributeError('prototype')
+ elif hasattr(self, 'see'):
+ return self.see
+ else:
+ params = ''
+
+ if hasattr(self, 'parameters'):
+ params = ', '.join(self.parameters.keys())
+
+ return '%s(%s)' % (self.function, params)
+
+class HTMLDocGenerator(object):
+ def __init__(self, file_ob):
+ self.categories = []
+
+ self.parse(file_ob)
+
+ def parse(self, file_ob):
+ self.tree = yaml.load(file_ob)
+
+ unimplemented = 0
+ total = 0
+
+ for name, category in self.tree.items():
+ if name.startswith('__'):
+ continue
+
+ current_category = []
+
+ for funct_id, function in category.iteritems():
+ f = Function('%s.%s' % (name, funct_id), function)
+
+ if f.unimplemented:
+ unimplemented += 1
+
+ total += 1
+ current_category.append(f)
+
+ self.categories.append((name, current_category))
+
+ def to_html(self):
+ html = []
+
+ html.append('<style type="text/css">%s</style>' % self.tree.get('__style__', ''))
+
+ for category, functions in self.categories:
+ html.append('<h2>%s</h2>' % category.title())
+
+ for funct in functions:
+ html.append('<a name="%s"></a>' % funct.id)
+ html.append('<h3>%s</h3>' % funct.se_route)
+ html.append('<div class="api">')
+
+ if hasattr(funct, 'see'):
+ html.append('<div class="see">see <a href="#%s">%s</a></div>' % (funct.see, funct.see))
+ html.append('</div>')
+ continue
+
+ if not funct.unimplemented:
+ html.append('<div class="prototype">%s</div>' % funct.prototype)
+
+ html.append('<div class="description">%s</div>' % funct.description)
+
+ if funct.unimplemented:
+ html.append('<div class="unimplemented">Unimplemented.</div>')
+ html.append('</div>')
+ continue
+
+
+ if hasattr(funct, 'returns'):
+ html.append('<div class="returns">Returns: <span>%s</span></div>' % funct.returns)
+
+ if hasattr(funct, 'parameters'):
+ html.append('<h4>Parameters</h4>')
+ html.append('<div class="params">')
+
+ for key, desc in funct.parameters.iteritems():
+ html.append('<div><span class="param_name">%s</span> <span class="param_desc">%s</span></div>' % (key, desc))
+
+ html.append('</div>')
+
+ if hasattr(funct, 'example'):
+ html.append('<h4>Example</h4>')
+ html.append('<pre class="example">%s</pre>' % funct.example)
+
+ html.append('</div>')
+
+ return '\n'.join(html)
+
+if __name__ == '__main__':
+ in_handle = open('api.yml')
+ out_handle = open('api.html', 'w')
+
+ docgen = HTMLDocGenerator(in_handle)
+ out_handle.write(docgen.to_html())
+
+ in_handle.close()
+ out_handle.close()
Oops, something went wrong.

0 comments on commit 15a3cb9

Please sign in to comment.