annotate document_it.py @ 9:62bd66061329

add a helpful help message
author Jeff Hammel <jhammel@mozilla.com>
date Mon, 01 Aug 2011 23:13:53 -0700
parents f7fa35f972f4
children 853214384bd0
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
1 #!/usr/bin/env python
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
2
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
3 """
9
62bd66061329 add a helpful help message
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
4 update MDN documentation from markdown
4
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
5
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
6 see:
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
7 http://developer.mindtouch.com/en/ref/MindTouch_API/POST%3Apages%2F%2F%7Bpageid%7D%2F%2Fcontents
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
8
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
9 The manifest format is in the form:
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
10
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
11 mozrunner/README.txt https://developer.mozilla.org/en/Mozrunner
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
12 jsbridge/README.txt https://developer.mozilla.org/en/JSbridge
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
13 mozmill/README.txt https://developer.mozilla.org/en/Mozmill
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
14 mozmill/docs/ https://developer.mozilla.org/en/Mozmill/
9
62bd66061329 add a helpful help message
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
15
62bd66061329 add a helpful help message
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
16 --dest sets the destination, e.g.
62bd66061329 add a helpful help message
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
17
62bd66061329 add a helpful help message
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
18 --dest http://developer.mozilla.org/
62bd66061329 add a helpful help message
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
19 --dest https://developer-stage9.mozilla.org/jhammel
62bd66061329 add a helpful help message
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
20 --dest path/to directory
62bd66061329 add a helpful help message
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
21
62bd66061329 add a helpful help message
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
22 By default, a new temporary directory will be created
0
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
23 """
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
24
5
3464eda1af80 better formatting for command line
Jeff Hammel <jhammel@mozilla.com>
parents: 4
diff changeset
25 import optparse
0
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
26 import os
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
27 import sys
9
62bd66061329 add a helpful help message
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
28 import tempfile
0
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
29 import urllib2
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
30
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
31 # necessary imports
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
32 try:
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
33 import markdown
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
34 except ImportError:
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
35 raise ImportError("markdown is not installed, run (e.g.):\neasy_install Markdown")
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
36
5
3464eda1af80 better formatting for command line
Jeff Hammel <jhammel@mozilla.com>
parents: 4
diff changeset
37 DIR=os.path.dirname(os.path.abspath(__file__)) # XXX currently unused
0
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
38
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
39 def find_readme(directory):
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
40 """find a README file in a directory"""
4
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
41 # XXX currently unused
5
3464eda1af80 better formatting for command line
Jeff Hammel <jhammel@mozilla.com>
parents: 4
diff changeset
42 README=['README.md', 'README.txt', 'README']
0
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
43 for name in README:
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
44 path = os.path.join(directory, name)
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
45 if os.path.exists(path):
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
46 return path
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
47
4
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
48 def parse_manifest(filename, directory=None):
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
49 """
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
50 reads a documentation manifest; returns a list of two-tuples:
6
5a4c1339b2f9 more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 5
diff changeset
51 [(filename, destination)]
4
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
52 """
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
53
6
5a4c1339b2f9 more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 5
diff changeset
54 assert os.path.exists(filename) and os.path.isfile(filename), "%s not found" % filename
5a4c1339b2f9 more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 5
diff changeset
55
4
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
56 if directory is None:
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
57 directory = os.path.dirname(os.path.abspath(filename))
5
3464eda1af80 better formatting for command line
Jeff Hammel <jhammel@mozilla.com>
parents: 4
diff changeset
58 lines = [line.strip() for line in file(filename).readlines()]
4
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
59 lines = [line for line in lines
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
60 if line and not line.startswith('#')]
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
61 items = []
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
62 for line in lines:
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
63 try:
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
64 f, url = line.split()
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
65 # TODO: include options as third segment (e.g. format=ReST)
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
66 except ValueError:
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
67 raise ValueError("illegal manifest line: '%s'" % line)
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
68
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
69 filename = os.path.join(directory, f)
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
70 if os.path.isdir(filename):
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
71 pass # TODO
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
72 else:
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
73 items.append((filename, url))
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
74 return items
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
75
0
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
76 def main(args=sys.argv[1:]):
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
77
9
62bd66061329 add a helpful help message
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
78 # default output directory
62bd66061329 add a helpful help message
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
79 default_dir = tempfile.mktemp()
62bd66061329 add a helpful help message
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
80
0
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
81 # parse command line options
4
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
82 usage = '%prog [options] manifest <manifest> <...>'
5
3464eda1af80 better formatting for command line
Jeff Hammel <jhammel@mozilla.com>
parents: 4
diff changeset
83
3464eda1af80 better formatting for command line
Jeff Hammel <jhammel@mozilla.com>
parents: 4
diff changeset
84 # description formatter
3464eda1af80 better formatting for command line
Jeff Hammel <jhammel@mozilla.com>
parents: 4
diff changeset
85 class PlainDescriptionFormatter(optparse.IndentedHelpFormatter):
3464eda1af80 better formatting for command line
Jeff Hammel <jhammel@mozilla.com>
parents: 4
diff changeset
86 def format_description(self, description):
3464eda1af80 better formatting for command line
Jeff Hammel <jhammel@mozilla.com>
parents: 4
diff changeset
87 if description:
3464eda1af80 better formatting for command line
Jeff Hammel <jhammel@mozilla.com>
parents: 4
diff changeset
88 return description + '\n'
3464eda1af80 better formatting for command line
Jeff Hammel <jhammel@mozilla.com>
parents: 4
diff changeset
89 else:
3464eda1af80 better formatting for command line
Jeff Hammel <jhammel@mozilla.com>
parents: 4
diff changeset
90 return ''
3464eda1af80 better formatting for command line
Jeff Hammel <jhammel@mozilla.com>
parents: 4
diff changeset
91
3464eda1af80 better formatting for command line
Jeff Hammel <jhammel@mozilla.com>
parents: 4
diff changeset
92 parser = optparse.OptionParser(usage=usage, description=__doc__, formatter=PlainDescriptionFormatter())
0
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
93 parser.add_option('-d', '--directory', dest='directory',
6
5a4c1339b2f9 more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 5
diff changeset
94 help='render the documentation from this directory')
4
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
95 parser.add_option('--dest', dest='dest',
9
62bd66061329 add a helpful help message
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
96 default=default_dir,
62bd66061329 add a helpful help message
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
97 help='base directory or URL of destination [DEFAULT: %default]')
4
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
98 parser.add_option('-u', '--user', dest='user',
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
99 help='user name')
6
5a4c1339b2f9 more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 5
diff changeset
100 parser.add_option('--list', dest='list', action='store_true', default=False,
5a4c1339b2f9 more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 5
diff changeset
101 help="list files")
9
62bd66061329 add a helpful help message
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
102 parser.add_option('--validate', dest='validate', # TODO unused
62bd66061329 add a helpful help message
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
103 action='store_true', default=False,
62bd66061329 add a helpful help message
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
104 help="validate the rendering but don't output")
4
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
105 options, manifests = parser.parse_args(args)
0
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
106
6
5a4c1339b2f9 more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 5
diff changeset
107 # print help if no manifests given
4
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
108 if not args:
5
3464eda1af80 better formatting for command line
Jeff Hammel <jhammel@mozilla.com>
parents: 4
diff changeset
109 parser.print_help()
4
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
110 parser.exit()
0
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
111
7
6bf82220a04c more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 6
diff changeset
112 # get base url
6bf82220a04c more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 6
diff changeset
113 if '://' in options.dest:
6bf82220a04c more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 6
diff changeset
114 baseurl = options.dest
6bf82220a04c more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 6
diff changeset
115 else:
6bf82220a04c more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 6
diff changeset
116 baseurl = 'file://' + options.dest
6bf82220a04c more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 6
diff changeset
117
6
5a4c1339b2f9 more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 5
diff changeset
118 # read the manifests
5a4c1339b2f9 more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 5
diff changeset
119 files = []
5a4c1339b2f9 more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 5
diff changeset
120 for manifest in manifests:
5a4c1339b2f9 more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 5
diff changeset
121 for item in parse_manifest(manifest):
5a4c1339b2f9 more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 5
diff changeset
122 if item not in files:
5a4c1339b2f9 more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 5
diff changeset
123 files.append(item)
5a4c1339b2f9 more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 5
diff changeset
124 if options.list:
5a4c1339b2f9 more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 5
diff changeset
125 for item in files:
7
6bf82220a04c more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 6
diff changeset
126 print '%s -> %s/%s' % (item[0], baseurl.rstrip('/'), item[1].lstrip('/'))
0
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
127
9
62bd66061329 add a helpful help message
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
128 if not files:
62bd66061329 add a helpful help message
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
129 return # you're done
62bd66061329 add a helpful help message
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
130
0
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
131 # render and upload READMEs
6
5a4c1339b2f9 more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 5
diff changeset
132 if options.directory:
8
f7fa35f972f4 more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
133
f7fa35f972f4 more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
134 # create a directory if needed
f7fa35f972f4 more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
135 if os.path.exists(options.directory):
f7fa35f972f4 more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
136 assert os.path.isdir(options.directory), "'%s' - not a directory" % options.directory
f7fa35f972f4 more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
137 else:
f7fa35f972f4 more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
138 os.makedirs(options.directory)
f7fa35f972f4 more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
139
f7fa35f972f4 more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
140 # TODO render to directory
9
62bd66061329 add a helpful help message
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
141 for src, dest in files:
62bd66061329 add a helpful help message
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
142 dest = os.path.join(options.dest, dest)
62bd66061329 add a helpful help message
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
143
6
5a4c1339b2f9 more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 5
diff changeset
144 else:
5a4c1339b2f9 more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 5
diff changeset
145 # TODO check credentials
5a4c1339b2f9 more stubbing
Jeff Hammel <jhammel@mozilla.com>
parents: 5
diff changeset
146 raise NotImplementedError
4
550f4b240e20 make almost look like what we want to do
Jeff Hammel <jhammel@mozilla.com>
parents: 2
diff changeset
147
9
62bd66061329 add a helpful help message
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
148 if options.dest = default_dir:
62bd66061329 add a helpful help message
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
149 print "Files rendered to %s" % default_dir
62bd66061329 add a helpful help message
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
150
0
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
151 if __name__ == '__main__':
665b2ae2ecc6 stub project for DocumentIt
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
152 main()