polish documentation. reference table of content specifically

docs/gen_reference_doc.py

@@ -61,6 +61,7 @@ static_links = \
 anon_index = 0
 
 category_mapping = {
+	'ed25519.hpp': 'ed25519',
 	'session.hpp': 'Session',
 	'add_torrent_params.hpp': 'Session',
 	'session_status.hpp': 'Session',
@@ -828,16 +829,16 @@ def print_link(name, target):
 	link_targets.append(target)
 	return "`%s`__" % name
 
-def dump_link_targets():
+def dump_link_targets(indent = ''):
 	global link_targets
 	ret = '\n'
 	for l in link_targets:
-		ret += '__ %s\n' % l
+		ret += '%s__ %s\n' % (indent, l)
 	link_targets = []
 	return ret
 
-def heading(string, c):
-	return '\n' + string + '\n' + (c * len(string)) + '\n'
+def heading(string, c, indent = ''):
+	return '\n' + indent + string + '\n' + indent + (c * len(string)) + '\n'
 
 def render_enums(out, enums, print_declared_reference):
 	for e in enums:
@@ -873,45 +874,65 @@ def render_enums(out, enums, print_declared_reference):
 
 		print >>out, dump_link_targets()
 
+sections = \
+{
+	'Core': 0,
+	'Session': 0,
+	'Settings': 0,
 
-out = open('reference.rst', 'w+')
-out.write('''==================================
-libtorrent reference documentation
-==================================
+	'Bencoding': 1,
+	'Bdecoding': 1,
+	'Filter': 1,
+	'Error Codes': 1,
+	'Create Torrents': 1,
 
-.. raw:: html
+	'ed25519': 2,
+	'String': 2,
+	'Utility': 2,
+	'Storage': 2,
+	'Custom Storage': 2,
+	'Plugins': 2,
 
-	<div style="column-count: 4; -webkit-column-count: 4; -moz-column-count: 4">
+	'Alerts': 3
+}
 
-''')
+def print_toc(out, categories, s):
+	for cat in categories:
+		if (s != 2 and cat not in sections) or \
+			(cat in sections and sections[cat] != s): continue
 
-for cat in categories:
-	print >>out, '%s' % heading(cat, '-')
+		print >>out, '\t.. rubric:: %s\n' % cat
 
 		if 'overview' in categories[cat]:
-		print >>out, '| overview__'
+			print >>out, '\t| overview__'
 
 		category_filename = categories[cat]['filename'].replace('.rst', '.html')
 		for c in categories[cat]['classes']:
-		print >>out, '| ' + print_link(c['name'], symbols[c['name']])
+			print >>out, '\t| ' + print_link(c['name'], symbols[c['name']])
 		for f in categories[cat]['functions']:
 			for n in f['names']:
-			print >>out, '| ' + print_link(n, symbols[n])
+				print >>out, '\t| ' + print_link(n, symbols[n])
 		for e in categories[cat]['enums']:
-		print >>out, '| ' + print_link(e['name'], symbols[e['name']])
+			print >>out, '\t| ' + print_link(e['name'], symbols[e['name']])
 		print >>out, ''
 
 		if 'overview' in categories[cat]:
-		print >>out, '__ %s#overview' % categories[cat]['filename'].replace('.rst', '.html')
-	print >>out, dump_link_targets()
+			print >>out, '\t__ %s#overview' % categories[cat]['filename'].replace('.rst', '.html')
+		print >>out, dump_link_targets('\t')
 
-out.write('''
 
-.. raw:: html
-
-	</div>
+out = open('reference.rst', 'w+')
+out.write('''=======================
+reference documentation
+=======================
 
 ''')
+
+for i in range(4):
+
+	out.write('.. container:: main-toc\n\n')
+	print_toc(out, categories, i)
+
 out.close()
 
 for cat in categories:

docs/makefile

@@ -19,6 +19,8 @@ REFERENCE_TARGETS = \
 	reference-RSS \
 	reference-Filter \
 	reference-Settings \
+	reference-Bdecoding \
+	reference-ed25519 \
 	manual-ref
 
 TARGETS = index \

docs/rst.css

@@ -35,6 +35,23 @@ h3 { text-transform: uppercase; }
 div.section p, div.section ul, div.section dl {
 }
 
+div.main-toc {
+	column-count: 4;
+	-webkit-column-count: 4;
+	-moz-column-count: 4;
+	border: 1px solid #999;
+	padding: 5px;
+	margin-bottom: 10px;
+}
+
+.rubric
+{
+	margin-top: 5px;
+	margin-bottom: 5px;
+	font-size: 120%;
+	font-weight: bold;
+}
+
 table.docinfo {
     text-align: left;
     float: right;
@@ -57,7 +74,7 @@ table.docinfo td {
 
 table.docinfo tr.field td, table.docinfo tr.field th {display: none;}
 
-h1.title { display: none; }
+#h1.title { display: none; }
 
 dt {
     font-size: 100%;

include/libtorrent/bencode.hpp

@@ -393,8 +393,8 @@ namespace libtorrent
 	
 	// These functions will encode data to bencoded or decode bencoded data.
 	// 
-	// If possible, bdecode() and bdecode_node should be preferred over this
-	// function.
+	// If possible, ``bdecode()`` producing a bdecode_node should be preferred
+	// over this function.
 	// 
 	// The entry_ class is the internal representation of the bencoded data
 	// and it can be used to retrieve information, an entry_ can also be build by

include/libtorrent/close_reason.hpp

@@ -37,7 +37,7 @@ POSSIBILITY OF SUCH DAMAGE.
 
 namespace libtorrent
 {
-	// these are all the reasons to disconnect a peer
+	// internal: these are all the reasons to disconnect a peer
 	// all reasons caused by the peer sending unexpected data
 	// are 256 and up.
 	enum close_reason_t

include/libtorrent/thread.hpp

@@ -63,6 +63,8 @@ namespace libtorrent
 
 	// pauses the calling thread at least for the specified
 	// number of milliseconds
+	// TODO: 3 remove this function. at the very least it should not be part
+	// of the API
 	TORRENT_EXPORT void sleep(int milliseconds);
 
 	struct TORRENT_EXTRA_EXPORT condition_variable

include/libtorrent/time.hpp

@@ -69,7 +69,10 @@ namespace libtorrent {
 	using boost::chrono::duration_cast;
 #endif
 
+	// internal
 	inline time_point min_time() { return (time_point::min)(); }
+
+	// internal
 	inline time_point max_time() { return (time_point::max)(); }
 
 	template<class T>

include/libtorrent/utp_stream.hpp

@@ -121,7 +121,7 @@ namespace libtorrent
 enum utp_socket_state_t
 { ST_DATA, ST_FIN, ST_STATE, ST_RESET, ST_SYN, NUM_TYPES };
 
-// extension headers. 2 is skipped because there is a deprecated
+// internal: extension headers. 2 is skipped because there is a deprecated
 // extension with that number in the wild
 enum utp_extensions_t
 { utp_no_extension = 0, utp_sack = 1, utp_close_reason = 3 };