You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
254 lines
7.5 KiB
254 lines
7.5 KiB
#!/usr/bin/python
|
|
# -*- coding: utf-8 -*-
|
|
#
|
|
# Copyright 2014 Google Inc. All Rights Reserved.
|
|
#
|
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
# you may not use this file except in compliance with the License.
|
|
# You may obtain a copy of the License at
|
|
#
|
|
# http://www.apache.org/licenses/LICENSE-2.0
|
|
#
|
|
# Unless required by applicable law or agreed to in writing, software
|
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
# See the License for the specific language governing permissions and
|
|
# limitations under the License.
|
|
|
|
"""Build wiki page with a list of all samples.
|
|
|
|
The information for the wiki page is built from data found in all the README
|
|
files in the samples. The format of the README file is:
|
|
|
|
|
|
Description is everything up to the first blank line.
|
|
|
|
api: plus (Used to look up the long name in discovery).
|
|
keywords: appengine (such as appengine, oauth2, cmdline)
|
|
|
|
The rest of the file is ignored when it comes to building the index.
|
|
"""
|
|
from __future__ import print_function
|
|
|
|
import httplib2
|
|
import itertools
|
|
import json
|
|
import os
|
|
import re
|
|
|
|
BASE_HG_URI = "http://code.google.com/p/google-api-python-client/source/" "browse/#hg"
|
|
|
|
http = httplib2.Http(".cache")
|
|
r, c = http.request("https://www.googleapis.com/discovery/v1/apis")
|
|
if r.status != 200:
|
|
raise ValueError("Received non-200 response when retrieving Discovery.")
|
|
|
|
# Dictionary mapping api names to their discovery description.
|
|
DIRECTORY = {}
|
|
for item in json.loads(c)["items"]:
|
|
if item["preferred"]:
|
|
DIRECTORY[item["name"]] = item
|
|
|
|
# A list of valid keywords. Should not be taken as complete, add to
|
|
# this list as needed.
|
|
KEYWORDS = {
|
|
"appengine": "Google App Engine",
|
|
"oauth2": "OAuth 2.0",
|
|
"cmdline": "Command-line",
|
|
"django": "Django",
|
|
"threading": "Threading",
|
|
"pagination": "Pagination",
|
|
"media": "Media Upload and Download",
|
|
}
|
|
|
|
|
|
def get_lines(name, lines):
|
|
"""Return lines that begin with name.
|
|
|
|
Lines are expected to look like:
|
|
|
|
name: space separated values
|
|
|
|
Args:
|
|
name: string, parameter name.
|
|
lines: iterable of string, lines in the file.
|
|
|
|
Returns:
|
|
List of values in the lines that match.
|
|
"""
|
|
retval = []
|
|
matches = itertools.ifilter(lambda x: x.startswith(name + ":"), lines)
|
|
for line in matches:
|
|
retval.extend(line[len(name) + 1 :].split())
|
|
return retval
|
|
|
|
|
|
def wiki_escape(s):
|
|
"""Detect WikiSyntax (i.e. InterCaps, a.k.a. CamelCase) and escape it."""
|
|
ret = []
|
|
for word in s.split():
|
|
if re.match(r"[A-Z]+[a-z]+[A-Z]", word):
|
|
word = "!%s" % word
|
|
ret.append(word)
|
|
return " ".join(ret)
|
|
|
|
|
|
def context_from_sample(api, keywords, dirname, desc, uri):
|
|
"""Return info for expanding a sample into a template.
|
|
|
|
Args:
|
|
api: string, name of api.
|
|
keywords: list of string, list of keywords for the given api.
|
|
dirname: string, directory name of the sample.
|
|
desc: string, long description of the sample.
|
|
uri: string, uri of the sample code if provided in the README.
|
|
|
|
Returns:
|
|
A dictionary of values useful for template expansion.
|
|
"""
|
|
if uri is None:
|
|
uri = BASE_HG_URI + dirname.replace("/", "%2F")
|
|
else:
|
|
uri = "".join(uri)
|
|
if api is None:
|
|
return None
|
|
else:
|
|
entry = DIRECTORY[api]
|
|
context = {
|
|
"api": api,
|
|
"version": entry["version"],
|
|
"api_name": wiki_escape(entry.get("title", entry.get("description"))),
|
|
"api_desc": wiki_escape(entry["description"]),
|
|
"api_icon": entry["icons"]["x32"],
|
|
"keywords": keywords,
|
|
"dir": dirname,
|
|
"uri": uri,
|
|
"desc": wiki_escape(desc),
|
|
}
|
|
return context
|
|
|
|
|
|
def keyword_context_from_sample(keywords, dirname, desc, uri):
|
|
"""Return info for expanding a sample into a template.
|
|
|
|
Sample may not be about a specific api.
|
|
|
|
Args:
|
|
keywords: list of string, list of keywords for the given api.
|
|
dirname: string, directory name of the sample.
|
|
desc: string, long description of the sample.
|
|
uri: string, uri of the sample code if provided in the README.
|
|
|
|
Returns:
|
|
A dictionary of values useful for template expansion.
|
|
"""
|
|
if uri is None:
|
|
uri = BASE_HG_URI + dirname.replace("/", "%2F")
|
|
else:
|
|
uri = "".join(uri)
|
|
context = {
|
|
"keywords": keywords,
|
|
"dir": dirname,
|
|
"uri": uri,
|
|
"desc": wiki_escape(desc),
|
|
}
|
|
return context
|
|
|
|
|
|
def scan_readme_files(dirname):
|
|
"""Scans all subdirs of dirname for README files.
|
|
|
|
Args:
|
|
dirname: string, name of directory to walk.
|
|
|
|
Returns:
|
|
(samples, keyword_set): list of information about all samples, the union
|
|
of all keywords found.
|
|
"""
|
|
samples = []
|
|
keyword_set = set()
|
|
|
|
for root, dirs, files in os.walk(dirname):
|
|
if "README" in files:
|
|
filename = os.path.join(root, "README")
|
|
with open(filename, "r") as f:
|
|
content = f.read()
|
|
lines = content.splitlines()
|
|
desc = " ".join(itertools.takewhile(lambda x: x, lines))
|
|
api = get_lines("api", lines)
|
|
keywords = get_lines("keywords", lines)
|
|
uri = get_lines("uri", lines)
|
|
if not uri:
|
|
uri = None
|
|
|
|
for k in keywords:
|
|
if k not in KEYWORDS:
|
|
raise ValueError(
|
|
"%s is not a valid keyword in file %s" % (k, filename)
|
|
)
|
|
keyword_set.update(keywords)
|
|
if not api:
|
|
api = [None]
|
|
samples.append((api[0], keywords, root[1:], desc, uri))
|
|
|
|
samples.sort()
|
|
|
|
return samples, keyword_set
|
|
|
|
|
|
def main():
|
|
# Get all the information we need out of the README files in the samples.
|
|
samples, keyword_set = scan_readme_files("./samples")
|
|
|
|
# Now build a wiki page with all that information. Accumulate all the
|
|
# information as string to be concatenated when were done.
|
|
page = ['<wiki:toc max_depth="3" />\n= Samples By API =\n']
|
|
|
|
# All the samples, grouped by API.
|
|
current_api = None
|
|
for api, keywords, dirname, desc, uri in samples:
|
|
context = context_from_sample(api, keywords, dirname, desc, uri)
|
|
if context is None:
|
|
continue
|
|
if current_api != api:
|
|
page.append(
|
|
"""
|
|
=== %(api_icon)s %(api_name)s ===
|
|
|
|
%(api_desc)s
|
|
|
|
Documentation for the %(api_name)s in [https://google-api-client-libraries.appspot.com/documentation/%(api)s/%(version)s/python/latest/ PyDoc]
|
|
|
|
"""
|
|
% context
|
|
)
|
|
current_api = api
|
|
|
|
page.append("|| [%(uri)s %(dir)s] || %(desc)s ||\n" % context)
|
|
|
|
# Now group the samples by keywords.
|
|
for keyword, keyword_name in KEYWORDS.iteritems():
|
|
if keyword not in keyword_set:
|
|
continue
|
|
page.append("\n= %s Samples =\n\n" % keyword_name)
|
|
page.append("<table border=1 cellspacing=0 cellpadding=8px>\n")
|
|
for _, keywords, dirname, desc, uri in samples:
|
|
context = keyword_context_from_sample(keywords, dirname, desc, uri)
|
|
if keyword not in keywords:
|
|
continue
|
|
page.append(
|
|
"""
|
|
<tr>
|
|
<td>[%(uri)s %(dir)s] </td>
|
|
<td> %(desc)s </td>
|
|
</tr>"""
|
|
% context
|
|
)
|
|
page.append("</table>\n")
|
|
|
|
print("".join(page))
|
|
|
|
|
|
if __name__ == "__main__":
|
|
main()
|