diff --git a/docs/contributing.rst b/docs/contributing.rst
index d1bda72cc..d1a640a43 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -34,7 +34,14 @@ enumerated on this page, please contact arvid@libtorrent.org or the `mailing lis
in general. Non-reference documentation is very much welcome as well, higher level
descriptions on how to configure libtorrent for various situations for instance.
The reference documentation for libtorrent is generated from the header files.
- For updates, please submit a `pull request`_.
+
+ Each heading in the online documentation has a short-cut link to file a new issue
+ against the documentation.
+
+ For updates, please submit a `pull request`_. All documentation is in
+ restructured text (rst_). All documentation is spell checked with hunspell
+ which can be invoked via ``make spell-check`` in the docs directory. If
+ words are missing, please add them to ``docs/hunspell/libtorrent.dic``
3. Code
Contributing code for new features or bug-fixes is highly welcome. If you're interested
@@ -50,10 +57,8 @@ For an overview of the internals of libtorrent, see the hacking_ page.
For outstanding things to do, see the `todo list`_ or the `sonarqube analysis`_ of master.
.. _hacking: hacking.html
-
.. _`pull request`: https://github.com/arvidn/libtorrent
-
.. _`todo list`: todo.html
-
.. _`sonarqube analysis`: https://sonarcloud.io/dashboard?id=libtorrent
+.. _rst: https://docutils.sourceforge.io/rst.html
diff --git a/docs/gen_reference_doc.py b/docs/gen_reference_doc.py
index 6d2af967c..1edd80876 100644
--- a/docs/gen_reference_doc.py
+++ b/docs/gen_reference_doc.py
@@ -2,6 +2,7 @@
# vim: tabstop=8 expandtab shiftwidth=4 softtabstop=4
from __future__ import print_function
+import urllib
import glob
import os
import sys
@@ -1087,6 +1088,7 @@ def render_enums(out, enums, print_declared_reference, header_level):
print('.. raw:: html\n', file=out)
print('\t' % e['name'], file=out)
print('', file=out)
+ dump_report_issue('enum ' + e['name'], out)
print(heading('enum %s' % e['name'], header_level), file=out)
print_declared_in(out, e)
@@ -1167,6 +1169,14 @@ def print_toc(out, categories, s):
print(dump_link_targets('\t'), file=out)
+def dump_report_issue(h, out):
+ print(('.. raw:: html\n\n\t[report issue]\n\n').format(
+ urllib.quote_plus(h),
+ urllib.quote_plus('Documentation under heading "' + h + '" could be improved')), file=out)
+
+
out = open('reference.rst', 'w+')
out.write('''=======================
reference documentation
@@ -1213,6 +1223,7 @@ __ reference.html
print('\t' % c['name'], file=out)
print('', file=out)
+ dump_report_issue('class ' + c['name'], out)
out.write('%s\n' % heading(c['name'], '-'))
print_declared_in(out, c)
c['desc'] = linkify_symbols(c['desc'])
@@ -1253,14 +1264,13 @@ __ reference.html
for f in c['fun']:
if f['desc'] == '':
continue
- title = ''
print('.. raw:: html\n', file=out)
for n in f['names']:
print('\t' % n, file=out)
print('', file=out)
- for n in f['names']:
- title += '%s ' % n
- print(heading(title.strip(), '.'), file=out)
+ h = ' '.join(f['names'])
+ dump_report_issue('%s::[%s]' % (c['name'], h), out)
+ print(heading(h, '.'), file=out)
block = '.. parsed-literal::\n\n'
@@ -1282,23 +1292,21 @@ __ reference.html
for n in f['names']:
print('\t' % n, file=out)
print('', file=out)
-
- for n in f['names']:
- print('%s ' % n, end=' ', file=out)
- print('', file=out)
+ h = ' '.join(f['names'])
+ dump_report_issue('%s::[%s]' % (c['name'], h), out)
+ print(h, file=out)
f['desc'] = linkify_symbols(f['desc'])
print('\t%s' % f['desc'].replace('\n', '\n\t'), file=out)
print(dump_link_targets(), file=out)
for f in functions:
- h = ''
print('.. raw:: html\n', file=out)
for n in f['names']:
print('\t' % n, file=out)
print('', file=out)
- for n in f['names']:
- h += '%s ' % n
+ h = ' '.join(f['names'])
+ dump_report_issue(h, out)
print(heading(h, '-'), file=out)
print_declared_in(out, f)
diff --git a/docs/hunspell/libtorrent.dic b/docs/hunspell/libtorrent.dic
index baec672f6..52391d3ca 100644
--- a/docs/hunspell/libtorrent.dic
+++ b/docs/hunspell/libtorrent.dic
@@ -510,3 +510,6 @@ cstdint
cloneable
inline
chrono
+hunspell
+online
+dic