jiigen666/libtorrent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

generate rst instead of html for reference documentation. This allows for RST markup in comments

Browse Source
This commit is contained in:
Arvid Norberg
2013-07-24 05:04:46 +00:00
parent c0da76ac84
commit e7804d717f
5 changed files with 146 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files

204
docs/gen_reference_doc.py
View File

@@ -84,7 +84,7 @@ def is_visible(desc):
def highlight_signature(s):
name = s.split('(')
name2 = name[0].split(' ')
name2[-1] = '<strong>' + name2[-1] + '</strong>'
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('''<html><head>
<link rel="stylesheet" href="style.css" type="text/css" />
</head><body>
<h1>libtorrent reference documentation</h1>
<div style="column-count: 5; -webkit-column-count: 5; -moz-column-count: 5">''')
def print_declared_in(out, o):
out.write('<p>Declared in <a href="../include/%s">"%s"</a></p>' % (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('<a href="%s">%s</a>' % (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
<div style="column-count: 4; -webkit-column-count: 4; -moz-column-count: 4">
''')
for cat in categories:
print >>out, '<h2>%s</h2><p>' % 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, '<a href="%s#%s">%s %s</a><br/>' % (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, '<a href="%s#%s">%s()</a><br/>' % (category_filename, name, name)
print >>out, '| ' + print_link(n + '()', category_filename + '#' + n)
for e in categories[cat]['enums']:
print >>out, '<a href="%s#%s">enum %s</a><br/>' % (category_filename, html_sanitize(e['name']), html_sanitize(e['name']))
print >>out, '</p>'
print >>out, '| ' + print_link(e['name'], category_filename + '#' + e['name'])
print >>out, ''
out.write('</body></html>')
print >>out, dump_link_targets()
out.write('''
.. raw:: html
</div>
''')
out.close()
for cat in categories:
@@ -584,105 +614,121 @@ for cat in categories:
functions = categories[cat]['functions']
enums = categories[cat]['enums']
out.write('''<html><head>
<link rel="stylesheet" href="style.css" type="text/css" />
</head><body><div id="container">''')
if 'overview' in categories[cat]:
out.write('<h1>%s</h1><p>%s</p>' % (cat, html_sanitize(categories[cat]['overview'])))
out.write('%s\n%s' % (heading(cat, '='), categories[cat]['overview']))
for c in classes:
out.write('<a name="%s"></a><h2>%s %s</h2>' % (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('<p>%s</p>' % html_sanitize(c['desc']))
out.write('%s\n\n.. parsed-literal::\n\t' % c['desc'])
out.write('<pre class="literal-block">')
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('};</pre>')
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, '<a name="%s"></a>' % name
print >>out, '<h3>'
for n in f['names']:
name = html_sanitize(n)
print >>out, '%s() ' % name
print >>out, '</h3>'
print >>out, '<blockquote><pre class="literal-block">'
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, '</pre></blockquote>'
print >>out, '<p>%s</p>' % 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, '<a name="%s::%s"></a><h3>enum %s</h3>' % (html_sanitize(e['name']), html_sanitize(c['name']), html_sanitize(e['name']))
print >>out, '<table><tr><th>value</th><th>description</th></tr>'
print >>out, heading('enum %s' % e['name'], '.')
width = [len('value'), len('description')]
for v in e['values']:
print >>out, '<tr><td>%s</td><td>%s</td></tr>' % (html_sanitize(v['name']), html_sanitize(v['desc']))
print >>out, '</table>'
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, '<a name="%s"></a>' % html_sanitize(c['name'] + '::' + n)
print >>out, '<dt>'
for n in f['names']:
print >>out, '%s ' % html_sanitize(n)
print >>out, '</dt><dd>%s</dd>' % 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, '<a name="%s"></a>' % name
print >>out, '<h2>'
for n in f['names']:
name = html_sanitize(n)
print >>out, '%s() ' % name
print >>out, '</h2>'
h += '%s() ' % n
print >>out, heading(h, '.')
print_declared_in(out, f)
print >>out, '<blockquote><pre class="literal-block">'
block = '.. parsed-literal::\n\n'
for s in f['signatures']:
print >>out, highlight_signature(html_sanitize(s))
print >>out, '</pre></blockquote>'
print >>out, '<p>%s</p>' % 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, '<a name="%s"></a><h2>enum %s</h2>' % (name, name)
print >>out, heading('enum %s' % e['name'], '.')
print_declared_in(out, e)
print >>out, '<table><tr><th>value</th><th>description</th></tr>'
for v in e['values']:
print >>out, '<tr><td>%s</td><td>%s</td></tr>' % (html_sanitize(v['name']), html_sanitize(v['desc']))
print >>out, '</table>'
out.write('</body></html>')
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()

20
docs/makefile
View File

@@ -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

2
docs/style.css
View File

@@ -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;

2
include/libtorrent/add_torrent_params.hpp
View File

@@ -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<boost::uint8_t> file_priorities;

7
include/libtorrent/rss.hpp
View File

@@ -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<feed> new_feed(aux::session_impl& ses, feed_settings const& sett);
boost::shared_ptr<feed> 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