From e7804d717fc91a13623b439f45e17e65fad2a5df Mon Sep 17 00:00:00 2001 From: Arvid Norberg Date: Wed, 24 Jul 2013 05:04:46 +0000 Subject: [PATCH] generate rst instead of html for reference documentation. This allows for RST markup in comments --- docs/gen_reference_doc.py | 204 +++++++++++++--------- docs/makefile | 20 ++- docs/style.css | 2 - include/libtorrent/add_torrent_params.hpp | 2 +- include/libtorrent/rss.hpp | 7 +- 5 files changed, 146 insertions(+), 89 deletions(-) diff --git a/docs/gen_reference_doc.py b/docs/gen_reference_doc.py index 6567102be..1d5ea2538 100644 --- a/docs/gen_reference_doc.py +++ b/docs/gen_reference_doc.py @@ -84,7 +84,7 @@ def is_visible(desc): def highlight_signature(s): name = s.split('(') name2 = name[0].split(' ') - name2[-1] = '' + name2[-1] + '' + name2[-1] = '**' + name2[-1] + '** ' name[0] = ' '.join(name2) return '('.join(name) @@ -209,6 +209,7 @@ def parse_class(lno, lines, filename): if l.startswith('//'): if verbose: print 'desc %s' % l l = l.split('//')[1] + if len(l) and l[0] == ' ': l = l[1:] context += l + '\n' continue @@ -298,6 +299,7 @@ def parse_enum(lno, lines, filename): if l.startswith('//'): if verbose: print 'desc %s' % l l = l.split('//')[1] + if len(l) and l[0] == ' ': l = l[1:] context += l + '\n' continue @@ -413,6 +415,7 @@ for filename in files: if l.startswith('//'): if verbose: print 'desc %s' % l l = l.split('//')[1] + if len(l) and l[0] == ' ': l = l[1:] context += l + '\n' continue @@ -521,7 +524,7 @@ categories = {} for c in classes: cat = categorize_symbol(c['name'], c['file']) if not cat in categories: - categories[cat] = { 'classes': [], 'functions': [], 'enums': [], 'filename': 'reference-%s.html' % cat.replace(' ', '_')} + categories[cat] = { 'classes': [], 'functions': [], 'enums': [], 'filename': 'reference-%s.rst' % cat.replace(' ', '_')} if c['file'] in overviews: categories[cat]['overview'] = overviews[c['file']] @@ -532,7 +535,7 @@ for c in classes: for f in functions: 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(' ', '_')} + categories[cat] = { 'classes': [], 'functions': [], 'enums': [], 'filename': 'reference-%s.rst' % cat.replace(' ', '_')} if f['file'] in overviews: categories[cat]['overview'] = overviews[f['file']] @@ -544,37 +547,64 @@ for f in functions: for e in enums: cat = categorize_symbol(e['name'], e['file']) if not cat in categories: - categories[cat] = { 'classes': [], 'functions': [], 'enums': [], 'filename': 'reference-%s.html' % cat.replace(' ', '_')} + categories[cat] = { 'classes': [], 'functions': [], 'enums': [], 'filename': 'reference-%s.rst' % cat.replace(' ', '_')} categories[cat]['enums'].append(e) symbols[e['name']] = categories[cat]['filename'] + '#' + html_sanitize(e['name']) -out = open('reference.html', 'w+') -out.write(''' - - -

libtorrent reference documentation

-
''') - def print_declared_in(out, o): - out.write('

Declared in "%s"

' % (o['file'], html_sanitize(o['file']))) + out.write('Declared in "%s"\n\n' % print_link(o['file'], '../include/%s' % o['file'])) -def print_link(out, name): - our.write('%s' % (symbols[name], name)) +link_targets = [] + +def print_link(name, target): + global link_targets + link_targets.append(target) + return "`%s`__" % name + +def dump_link_targets(): + global link_targets + ret = '' + for l in link_targets: + ret += '__ %s\n' % l + link_targets = [] + return ret + +def heading(string, c): + return string + '\n' + (c * len(string)) + '\n' + +out = open('reference.rst', 'w+') +out.write('''================================== +libtorrent reference documentation +================================== + +.. raw:: html + +
+ +''') for cat in categories: - print >>out, '

%s

' % cat - category_filename = categories[cat]['filename'] + print >>out, '%s' % heading(cat, '-') + + category_filename = categories[cat]['filename'].replace('.rst', '.html') for c in categories[cat]['classes']: - print >>out, '%s %s
' % (category_filename, html_sanitize(c['name']), html_sanitize(c['type']), html_sanitize(c['name'])) + print >>out, '| ' + print_link(c['name'], category_filename + '#' + c['name']) for f in categories[cat]['functions']: for n in f['names']: - name = html_sanitize(n) - print >>out, '%s()
' % (category_filename, name, name) + print >>out, '| ' + print_link(n + '()', category_filename + '#' + n) for e in categories[cat]['enums']: - print >>out, 'enum %s
' % (category_filename, html_sanitize(e['name']), html_sanitize(e['name'])) - print >>out, '

' + print >>out, '| ' + print_link(e['name'], category_filename + '#' + e['name']) + print >>out, '' -out.write('') +print >>out, dump_link_targets() + +out.write(''' + +.. raw:: html + +
+ +''') out.close() for cat in categories: @@ -584,105 +614,121 @@ for cat in categories: functions = categories[cat]['functions'] enums = categories[cat]['enums'] - out.write(''' - -
''') - if 'overview' in categories[cat]: - out.write('

%s

%s

' % (cat, html_sanitize(categories[cat]['overview']))) + out.write('%s\n%s' % (heading(cat, '='), categories[cat]['overview'])) for c in classes: - out.write('

%s %s

' % (html_sanitize(c['name']), html_sanitize(c['type']), html_sanitize(c['name']))) + out.write('%s\n' % heading(c['name'], '-')) print_declared_in(out, c) - out.write('

%s

' % html_sanitize(c['desc'])) + out.write('%s\n\n.. parsed-literal::\n\t' % c['desc']) - out.write('
')
-		print >>out, '%s\n{' % html_sanitize(c['decl'])
+		block = '\n%s\n{\n' % c['decl']
 		for f in c['fun']:
 			for s in f['signatures']:
-				print >>out, '   %s' % highlight_signature(html_sanitize(s.replace('\n', '\n   ')))
+				block += '   %s\n' % highlight_signature(s.replace('\n', '\n   '))
 
-		if len(c['fun']) > 0 and len(c['enums']) + len(c['fields']) > 0: print >>out, ''
+		if len(c['fun']) > 0 and len(c['enums']) > 0: block += '\n'
 
 		first = True
 		for e in c['enums']:
 			if not first:
-				print >>out, ''
+				block += '\n'
 			first = False
-			print >>out,'   enum %s\n   {' % html_sanitize(e['name'])
+			block += '   enum %s\n   {\n' % e['name']
 			for v in e['values']:
-				print >>out,'      %s,' % html_sanitize(v['name'])
-			print >>out,'   };'
+				block += '      %s,\n' % v['name']
+			block += '   };\n'
 
-		if len(c['fun']) + len(c['enums']) > 0 and len(c['fields']): print >>out, ''
+		if len(c['fun']) + len(c['enums']) > 0 and len(c['fields']): block += '\n'
 
 		for f in c['fields']:
 			for s in f['signatures']:
-				print >>out, '   %s' % html_sanitize(s)
+				block += '   %s\n' % s
 
-		out.write('};
') + block += '};' + + print >>out, block.replace('\n', '\n\t') + '\n' for f in c['fun']: if f['desc'] == '': continue + title = '' for n in f['names']: - name = html_sanitize(n) - print >>out, '' % name - print >>out, '

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

' - print >>out, '
'
+				title += '%s() ' % n
+			print >>out, heading(title.strip(), '.')
+
+			block = '.. parsed-literal::\n\n'
+
 			for s in f['signatures']:
-				print >>out, highlight_signature(html_sanitize(s.replace('\n', '\n   ')))
-			print >>out, '
' - print >>out, '

%s

' % html_sanitize(f['desc']) + block += highlight_signature(s.replace('\n', '\n ')) + '\n' + print >>out, '%s\n' % block.replace('\n', '\n\t') + print >>out, '%s' % f['desc'] for e in c['enums']: if e['desc'] == '': continue - print >>out, '

enum %s

' % (html_sanitize(e['name']), html_sanitize(c['name']), html_sanitize(e['name'])) - print >>out, '' + print >>out, heading('enum %s' % e['name'], '.') + width = [len('value'), len('description')] for v in e['values']: - print >>out, '' % (html_sanitize(v['name']), html_sanitize(v['desc'])) - print >>out, '
valuedescription
%s%s
' + width[0] = max(width[0], len(v['name'])) + for d in v['desc'].split('\n'): + width[1] = max(width[1], len(d)) + + print >>out, '+-' + ('-' * width[0]) + '-+-' + ('-' * width[1]) + '-+' + print >>out, '| ' + 'value'.ljust(width[0]) + ' | ' + 'description'.ljust(width[1]) + ' |' + print >>out, '+=' + ('=' * width[0]) + '=+=' + ('=' * width[1]) + '=+' + for v in e['values']: + d = v['desc'].split('\n') + if len(d) == 0: d = [''] + print >>out, '| ' + v['name'].ljust(width[0]) + ' | ' + d[0].ljust(width[1]) + ' |' + for s in d[1:]: + print >>out, '| ' + (' ' * width[0]) + ' | ' + s.ljust(width[1]) + ' |' + print >>out, '+-' + ('-' * width[0]) + '-+-' + ('-' * width[1]) + '-+' + print >>out, '' for f in c['fields']: if f['desc'] == '': continue 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']) + print >>out, '%s ' % n, + print >>out, '' + print >>out, '\t%s' % f['desc'].replace('\n', '\n\t') for f in functions: + h = '' for n in f['names']: - name = html_sanitize(n) - print >>out, '' % name - print >>out, '

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

' + h += '%s() ' % n + print >>out, heading(h, '.') print_declared_in(out, f) - print >>out, '
'
 
+		block = '.. parsed-literal::\n\n'
 		for s in f['signatures']:
-			print >>out, highlight_signature(html_sanitize(s))
-		print >>out, '
' - print >>out, '

%s

' % html_sanitize(f['desc']) + block += highlight_signature(s) + '\n' + + print >>out, '%s\n' % block.replace('\n', '\n\t') + print >>out, f['desc'] for e in enums: - name = html_sanitize(e['name']) - print >>out, '

enum %s

' % (name, name) + print >>out, heading('enum %s' % e['name'], '.') print_declared_in(out, e) - print >>out, '' - for v in e['values']: - print >>out, '' % (html_sanitize(v['name']), html_sanitize(v['desc'])) - print >>out, '
valuedescription
%s%s
' - out.write('') + width = [len('value'), len('description')] + for v in e['values']: + width[0] = max(width[0], len(v['name'])) + for d in v['desc'].split('\n'): + width[1] = max(width[1], len(d)) + + print >>out, '+-' + ('-' * width[0]) + '-+-' + ('-' * width[1]) + '-+' + print >>out, '| ' + 'value'.ljust(width[0]) + ' | ' + 'description'.ljust(width[1]) + ' |' + print >>out, '+=' + ('=' * width[0]) + '=+=' + ('=' * width[1]) + '=+' + for v in e['values']: + d = v['desc'].split('\n') + if len(d) == 0: d = [''] + print >>out, '| ' + v['name'].ljust(width[0]) + ' | ' + d[0].ljust(width[1]) + ' |' + for s in d[1:]: + print >>out, '| ' + (' ' * width[0]) + ' | ' + s.ljust(width[1]) + ' |' + print >>out, '+-' + ('-' * width[0]) + '-+-' + ('-' * width[1]) + '-+' + print >>out, '' + + print >>out, dump_link_targets() + out.close() diff --git a/docs/makefile b/docs/makefile index 14a5bcdca..db92f402c 100644 --- a/docs/makefile +++ b/docs/makefile @@ -22,11 +22,25 @@ TARGETS = index \ running_tests \ utp \ tuning \ - hacking + hacking \ + reference \ + reference-Core \ + reference-String \ + reference-Network \ + reference-Plugins \ + reference-Create_Torrents \ + reference-Error_codes \ + reference-Time \ + reference-Storage \ + reference-File \ + reference-Utility \ + reference-Bencoding \ + reference-Alerts \ + reference-RSS FIGURES = read_disk_buffers write_disk_buffers troubleshooting -html: $(TARGETS:=.html) $(FIGURES:=.png) todo.html reference.html +html: $(TARGETS:=.html) $(FIGURES:=.png) todo.html pdf: $(TARGETS:=.pdf) $(FIGURES:=.eps) @@ -37,7 +51,7 @@ all: html todo.html:gen_todo.py ../src/*.cpp ../include/libtorrent/*.hpp python gen_todo.py -reference.html:gen_reference_doc.py ../include/libtorrent/*.hpp +reference.rst:gen_reference_doc.py ../include/libtorrent/*.hpp python gen_reference_doc.py %.epub:%.rst diff --git a/docs/style.css b/docs/style.css index d8bf30b49..023cb6e6c 100644 --- a/docs/style.css +++ b/docs/style.css @@ -118,7 +118,6 @@ div.section p, div.section ul, div.section dl { #header { height: 116px; - width: 695px; background: url(../img/orange.png) #FDA72A no-repeat top left; } @@ -135,7 +134,6 @@ div.section p, div.section ul, div.section dl { #footer { clear: both; - width: 695px; height: 49px; background: #D3D3D3 url(../img/footer.png) no-repeat left top; text-align: center; diff --git a/include/libtorrent/add_torrent_params.hpp b/include/libtorrent/add_torrent_params.hpp index 03d059e51..1a4d938bd 100644 --- a/include/libtorrent/add_torrent_params.hpp +++ b/include/libtorrent/add_torrent_params.hpp @@ -262,7 +262,7 @@ namespace libtorrent // constructor functions, if any (see `add_extension()`_). void* userdata; - // can be set to control the initial file priorities when adding + // can be set to control the initial file priorities when adding // a torrent. The semantics are the same as for ``torrent_handle::prioritize_files()``. std::vector file_priorities; diff --git a/include/libtorrent/rss.hpp b/include/libtorrent/rss.hpp index a696285ba..ea375eca3 100644 --- a/include/libtorrent/rss.hpp +++ b/include/libtorrent/rss.hpp @@ -64,7 +64,6 @@ namespace libtorrent torrent_handle TORRENT_EXPORT add_feed_item(session& s, feed_item const& fi , add_torrent_params const& p); #endif - torrent_handle TORRENT_EXPORT add_feed_item(session& s, feed_item const& fi , add_torrent_params const& p, error_code& ec); @@ -72,7 +71,7 @@ namespace libtorrent // and configuration for a specific feed. All of // these settings can be changed by the user // after adding the feed - struct feed_settings + struct TORRENT_EXPORT feed_settings { feed_settings() : auto_download(true) @@ -96,7 +95,7 @@ namespace libtorrent add_torrent_params add_args; }; - struct feed_status + struct TORRENT_EXPORT feed_status { feed_status(): last_update(0), next_update(0) , updating(false), ttl(0) {} @@ -130,7 +129,7 @@ namespace libtorrent struct feed_state; class http_parser; - boost::shared_ptr new_feed(aux::session_impl& ses, feed_settings const& sett); + boost::shared_ptr TORRENT_EXPORT new_feed(aux::session_impl& ses, feed_settings const& sett); // this is the internal object holding all state about an // RSS feed. All user interaction with this object