From 117ad861587e7dac1d07aa8dcbb6f6e152847aa4 Mon Sep 17 00:00:00 2001 From: Arvid Norberg Date: Sun, 21 Jul 2013 05:04:04 +0000 Subject: [PATCH] polish documentation --- docs/gen_reference_doc.py | 95 ++++++++++++++++++++++--------------- docs/style.css | 99 ++++++++++++++++++++++++++++++++++----- 2 files changed, 144 insertions(+), 50 deletions(-) diff --git a/docs/gen_reference_doc.py b/docs/gen_reference_doc.py index 62cd11018..34aec8b15 100644 --- a/docs/gen_reference_doc.py +++ b/docs/gen_reference_doc.py @@ -68,6 +68,15 @@ def categorize_symbol(name, filename): return 'Core' +def first_item(itr): + for i in itr: + return i + return None + +def highlight_signature(s): + name = s.split('(')[0].split(' ')[-1].strip() + return s.replace(name, '' + name + '') + def html_sanitize(s): ret = '' for i in s: @@ -130,7 +139,7 @@ def parse_function(lno, lines, filename): lno = consume_block(lno - 1, lines) signature += ';' - return [{ 'file': filename[11:], 'overloads': [{'signature': signature, 'name': signature.split('(')[0].split(' ')[-1].strip()}]}, lno] + return [{ 'file': filename[11:], 'signatures': set([ signature ]), 'names': set([ signature.split('(')[0].split(' ')[-1].strip()])}, lno] if len(signature) > 0: print '\x1b[31mFAILED TO PARSE FUNCTION\x1b[0m %s\nline: %d\nfile: %s' % (signature, lno, filename) return [None, lno] @@ -214,7 +223,8 @@ def parse_class(lno, lines, filename): current_fun, lno = parse_function(lno - 1, lines, filename) if current_fun != None: if context == '' and blanks == 0 and len(funs): - funs[-1]['overloads'] += current_fun['overloads'] + funs[-1]['signatures'].update(current_fun['signatures']) + funs[-1]['names'].update(current_fun['names']) else: current_fun['desc'] = context funs.append(current_fun) @@ -223,8 +233,14 @@ def parse_class(lno, lines, filename): continue if looks_like_variable(l): - fields.append({ 'signature': l, 'name': l.split(' ')[-1].split(':')[0].split(';')[0], 'desc': context}) + n = l.split(' ')[-1].split(':')[0].split(';')[0] + if context == '' and blanks == 0 and len(fields): + fields[-1]['names'].append(n) + fields[-1]['signatures'].append(l) + else: + fields.append({'signatures': [l], 'names': [n], 'desc': context}) context = '' + blanks = 0 continue if l.startswith('enum '): @@ -398,7 +414,8 @@ for filename in files: current_fun, lno = parse_function(lno - 1, lines, filename) if current_fun != None: if context == '' and blanks == 0 and len(functions): - functions[-1]['overloads'] += current_fun['overloads'] + functions[-1]['signatures'].update(current_fun['signatures']) + functions[-1]['names'].update(current_fun['names']) else: current_fun['desc'] = context functions.append(current_fun) @@ -434,13 +451,14 @@ if dump: for c in classes: print '\x1b[4m%s\x1b[0m %s\n{' % (c['type'], c['name']) for f in c['fun']: - for o in f['overloads']: - print ' %s' % o['signature'].replace('\n', '\n ') + for s in f['signatures']: + print ' %s' % s.replace('\n', '\n ') if len(c['fun']) > 0 and len(c['fields']) > 0: print '' for f in c['fields']: - print ' %s' % f['signature'] + for s in f['signatures']: + print ' %s' % s if len(c['fields']) > 0 and len(c['enums']) > 0: print '' @@ -470,11 +488,11 @@ for c in classes: symbols[c['name']] = categories[cat]['filename'] + '#' + html_sanitize(c['name']) for f in functions: - cat = categorize_symbol(f['overloads'][0]['name'], f['file']) + cat = categorize_symbol(first_item(f['names']), f['file']) if not cat in categories: categories[cat] = { 'classes': [], 'functions': [], 'enums': [], 'filename': 'reference-%s.html' % cat.replace(' ', '_')} - for o in f['overloads']: - symbols[o['name']] = categories[cat]['filename'] + '#' + html_sanitize(o['name']) + for n in f['names']: + symbols[n] = categories[cat]['filename'] + '#' + html_sanitize(n) categories[cat]['functions'].append(f) for e in enums: @@ -486,8 +504,6 @@ for e in enums: out = open('reference.html', 'w+') out.write(''' - -

libtorrent reference documentation

@@ -505,13 +521,14 @@ for cat in categories: for c in categories[cat]['classes']: print >>out, '%s %s
' % (category_filename, html_sanitize(c['name']), html_sanitize(c['type']), html_sanitize(c['name'])) for f in categories[cat]['functions']: - name = html_sanitize(f['overloads'][0]['name']) - print >>out, '%s()
' % (category_filename, name, name) + for n in f['names']: + name = html_sanitize(n) + print >>out, '%s()
' % (category_filename, name, name) for e in categories[cat]['enums']: print >>out, 'enum %s
' % (category_filename, html_sanitize(e['name']), html_sanitize(e['name'])) print >>out, '

' -out.write('') +out.write('') out.close() for cat in categories: @@ -522,10 +539,8 @@ for cat in categories: enums = categories[cat]['enums'] out.write(''' - - - ''') +
''') for c in classes: out.write('

%s %s

' % (html_sanitize(c['name']), html_sanitize(c['type']), html_sanitize(c['name']))) @@ -535,9 +550,8 @@ for cat in categories: out.write('
')
 		print >>out, '%s\n{' % html_sanitize(c['decl'])
 		for f in c['fun']:
-			for o in f['overloads']:
-				name = html_sanitize(o['name'])
-				print >>out, '   %s' % html_sanitize(o['signature'].replace('\n', '\n   ')).replace(name, '' + name + '')
+			for s in f['signatures']:
+				print >>out, '   %s' % highlight_signature(html_sanitize(s.replace('\n', '\n   ')))
 
 		if len(c['fun']) > 0 and len(c['enums']) + len(c['fields']) > 0: print >>out, ''
 
@@ -554,24 +568,24 @@ for cat in categories:
 		if len(c['fun']) + len(c['enums']) > 0 and len(c['fields']): print >>out, ''
 
 		for f in c['fields']:
-			print >>out, '   %s' % html_sanitize(f['signature'])
+			for s in f['signatures']:
+				print >>out, '   %s' % html_sanitize(s)
 
 		out.write('};
') for f in c['fun']: if f['desc'] == '': continue - for o in f['overloads']: - name = html_sanitize(o['name']) + for n in f['names']: + name = html_sanitize(n) print >>out, '' % name print >>out, '

' - for o in f['overloads']: - name = html_sanitize(o['name']) + for n in f['names']: + name = html_sanitize(n) print >>out, '%s() ' % name print >>out, '

' print >>out, '
'
-			for o in f['overloads']:
-				name = html_sanitize(o['name'])
-				print >>out, html_sanitize(o['signature'].replace('\n', '\n   ')).replace(name, '' + name + '')
+			for s in f['signatures']:
+				print >>out, highlight_signature(html_sanitize(s.replace('\n', '\n   ')))
 			print >>out, '
' print >>out, '

%s

' % html_sanitize(f['desc']) @@ -585,24 +599,29 @@ for cat in categories: for f in c['fields']: if f['desc'] == '': continue - print >>out, '
%s
' % (html_sanitize(c['name'] + '::' + f['name']), html_sanitize(f['name'])) - print >>out, '
%s
' % html_sanitize(f['desc']) + for n in f['names']: + print >>out, '' % html_sanitize(c['name'] + '::' + n) + + print >>out, '
' + for n in f['names']: + print >>out, '%s ' % html_sanitize(n) + print >>out, '
%s
' % html_sanitize(f['desc']) for f in functions: - for o in f['overloads']: - name = html_sanitize(o['name']) + for n in f['names']: + name = html_sanitize(n) print >>out, '' % name print >>out, '

' - for o in f['overloads']: - name = html_sanitize(o['name']) + for n in f['names']: + name = html_sanitize(n) print >>out, '%s() ' % name print >>out, '

' print_declared_in(out, f) print >>out, '
'
-		for o in f['overloads']:
-			name = html_sanitize(o['name'])
-			print >>out, html_sanitize(o['signature']).replace(name, '' + name + '')
+
+		for s in f['signatures']:
+			print >>out, highlight_signature(html_sanitize(s))
 		print >>out, '
' print >>out, '

%s

' % html_sanitize(f['desc']) diff --git a/docs/style.css b/docs/style.css index 90ef3ce50..6cbfe8456 100644 --- a/docs/style.css +++ b/docs/style.css @@ -1,5 +1,3 @@ -html>body { font-size: 13px; } - .entry { min-height: 135px; } #main { @@ -11,23 +9,19 @@ html>body { font-size: 13px; } /* Base elements */ * {margin: 0; padding: 0;} -body { font: 0.8125em Verdana, sans-serif;} +body, table { font: 1em Verdana, sans-serif;} h1, h2, h3 { font: 1.5em Georgia "Times New Roman", serif; - letter-spacing: 1px; +/* letter-spacing: 1px; */ padding-bottom: 0.5em; + font-weight: bold; } h1 { font-size: 180%; } h2 { font-size: 130%; } h3 { font-size: 100%; } -p { - font-size: 92%; - line-height: 1.4em; -} - a { text-decoration: none; color: #8D370A; @@ -81,6 +75,88 @@ div.section div.section div.section { div.section p, div.section ul, div.section dl { } +#container { + text-align: left; + width: 700px; + margin: 0 auto; + position: relative; +} + +#container { + text-align: left; + width: 700px; + margin: 0 auto; + position: relative; +} + +#headerNav { +} + +#headerNav ul { + margin: 2px; + list-style: none; + font-family: Tahoma; + text-align: right; + text-transform: uppercase; + line-height: 1em; +} + +#headerNav ul li { + display: inline; + border-left: solid 1px #ccc; + padding-left: 10px; + padding-right: 10px; + margin: 0; + font-size: 80%; +} + +#headerNav ul li.first { + border: 0; +} + +#headerNav ul li a { + border: none; + color: #666; +} + +#headerNav ul li a:hover { + background: #eee; +} + +#header { + height: 116px; + width: 695px; + background: url(../img/orange.png) #FDA72A no-repeat top left; +} + +#header h1 { + margin: 0; + padding: 0; + float: right; + width: 536px; + height: 116px; + background: url(../img/logo.png); +} + +#header h1 span, #header h2 { display: none; } + +#footer { + clear: both; + width: 695px; + height: 49px; + background: #D3D3D3 url(../img/footer.png) no-repeat left top; + text-align: center; + margin-bottom: 1em; +} + +#footer span { + line-height: 49px; + font-size: 88%; + text-align: center; + color: #777; + display: block; +} + table.docinfo { text-align: left; float: right; @@ -106,18 +182,17 @@ table.docinfo tr.field td, table.docinfo tr.field th {display: none;} h1.title { text-align: center; } dt { - font-size: 100%; line-height: 1.2em; + margin-bottom: 0.5em; color: #315586; color: #000; - font-weight: bold; + font-style: italic; } dd { line-height: 1em; margin-left: 1em; margin-bottom: 1em; - font-size: 92%; } tt {