From a76b2a40b083619c4dd57a801b2c79f0d81e2063 Mon Sep 17 00:00:00 2001
From: Arvid Norberg <arvid@libtorrent.org>
Date: Fri, 13 Mar 2015 05:42:18 +0000
Subject: [PATCH] polish documentation. reference table of content specifically

---
 docs/gen_reference_doc.py           | 93 ++++++++++++++++++-----------
 docs/makefile                       |  2 +
 docs/rst.css                        | 19 +++++-
 include/libtorrent/bencode.hpp      |  4 +-
 include/libtorrent/close_reason.hpp |  2 +-
 include/libtorrent/thread.hpp       |  2 +
 include/libtorrent/time.hpp         |  3 +
 include/libtorrent/utp_stream.hpp   |  2 +-
 8 files changed, 86 insertions(+), 41 deletions(-)

diff --git a/docs/gen_reference_doc.py b/docs/gen_reference_doc.py
index 0c7072465..0540e05cd 100644
--- a/docs/gen_reference_doc.py
+++ b/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,
+
+	'Bencoding': 1,
+	'Bdecoding': 1,
+	'Filter': 1,
+	'Error Codes': 1,
+	'Create Torrents': 1,
+
+	'ed25519': 2,
+	'String': 2,
+	'Utility': 2,
+	'Storage': 2,
+	'Custom Storage': 2,
+	'Plugins': 2,
+
+	'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
+
+		print >>out, '\t.. rubric:: %s\n' % cat
+
+		if 'overview' in categories[cat]:
+			print >>out, '\t| overview__'
+
+		category_filename = categories[cat]['filename'].replace('.rst', '.html')
+		for c in categories[cat]['classes']:
+			print >>out, '\t| ' + print_link(c['name'], symbols[c['name']])
+		for f in categories[cat]['functions']:
+			for n in f['names']:
+				print >>out, '\t| ' + print_link(n, symbols[n])
+		for e in categories[cat]['enums']:
+			print >>out, '\t| ' + print_link(e['name'], symbols[e['name']])
+		print >>out, ''
+
+		if 'overview' in categories[cat]:
+			print >>out, '\t__ %s#overview' % categories[cat]['filename'].replace('.rst', '.html')
+		print >>out, dump_link_targets('\t')
+
 
 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">
+out.write('''=======================
+reference documentation
+=======================
 
 ''')
 
-for cat in categories:
-	print >>out, '%s' % heading(cat, '-')
+for i in range(4):
 
-	if 'overview' in categories[cat]:
-		print >>out, '| overview__'
+	out.write('.. container:: main-toc\n\n')
+	print_toc(out, categories, i)
 
-	category_filename = categories[cat]['filename'].replace('.rst', '.html')
-	for c in categories[cat]['classes']:
-		print >>out, '| ' + 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])
-	for e in categories[cat]['enums']:
-		print >>out, '| ' + 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()
-
-out.write('''
-
-.. raw:: html
-
-	</div>
-
-''')
 out.close()
 
 for cat in categories:
diff --git a/docs/makefile b/docs/makefile
index 093049601..dc8a68e47 100644
--- a/docs/makefile
+++ b/docs/makefile
@@ -19,6 +19,8 @@ REFERENCE_TARGETS = \
 	reference-RSS \
 	reference-Filter \
 	reference-Settings \
+	reference-Bdecoding \
+	reference-ed25519 \
 	manual-ref
 
 TARGETS = index \
diff --git a/docs/rst.css b/docs/rst.css
index 8f016308f..c21cd14dc 100644
--- a/docs/rst.css
+++ b/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%;
diff --git a/include/libtorrent/bencode.hpp b/include/libtorrent/bencode.hpp
index f5fc92f67..16b86414a 100644
--- a/include/libtorrent/bencode.hpp
+++ b/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
diff --git a/include/libtorrent/close_reason.hpp b/include/libtorrent/close_reason.hpp
index b88cdc976..e7da200f7 100644
--- a/include/libtorrent/close_reason.hpp
+++ b/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
diff --git a/include/libtorrent/thread.hpp b/include/libtorrent/thread.hpp
index 8350cc76e..6687c348c 100644
--- a/include/libtorrent/thread.hpp
+++ b/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
diff --git a/include/libtorrent/time.hpp b/include/libtorrent/time.hpp
index f1d55c95a..2be60f8ce 100644
--- a/include/libtorrent/time.hpp
+++ b/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>
diff --git a/include/libtorrent/utp_stream.hpp b/include/libtorrent/utp_stream.hpp
index 2754a305a..629d9c597 100644
--- a/include/libtorrent/utp_stream.hpp
+++ b/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 };