[Docs] Reorganise and add sections from wiki

- Change the layout and contents of docs to be better organised and
  follow ideas from: https://www.divio.com/blog/documentation/
- Use markdown for non-technical documents to speed up writing.
- Added new sections and imported documents from Trac wiki.

Build fixes:

- Added a patch to fix recommonmark 0.4 and doc referencing:
    https://github.com/rtfd/recommonmark/issues/93
- Set docs build in tox to Py2.7 since there are problems with autodoc
  mocking multiple inheritance on Python 3 resulting in metaclass errors.
- Supressed warning about `modules.rst` not in the toctree by creating
  a static `modules.rst` with `:orphan:` file directive and add to git.
  Also skip creating this toc file with sphinx-apidoc in setup and tox.
- Simplified finding exported RPC and JSON API methods by adding an
  autodoc custom class directive. Removed unneeded __rpcapi.py.

1 files changed, 27 insertions, 3 deletions

diff --git a/docs/source/conf.py b/docs/source/conf.py
index d24ccf8db..4d70c35bd 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -16,13 +16,28 @@ import sys
 from datetime import date
 
 import pkg_resources
+from recommonmark.states import DummyStateMachine
 from recommonmark.transform import AutoStructify
+from sphinx.ext.autodoc import ClassDocumenter, bool_option
 
 try:
     from ...version import get_version
 except ImportError:
     get_version = None
 
+
+# Monkey patch
+class PatchDummyStateMachine(DummyStateMachine):
+    """Fix recommonmark 0.4 doc reference issues."""
+
+    def run_role(self, name, *args, **kwargs):
+        if name == 'doc':
+            name = 'any'
+        return DummyStateMachine.run_role(self, name, *args, **kwargs)
+
+
+DummyStateMachine = PatchDummyStateMachine
+
 # Must add these for autodoc to import packages successully
 __builtin__.__dict__['_'] = lambda x: x
 __builtin__.__dict__['_n'] = lambda s, p, n: s if n == 1 else p
@@ -271,9 +286,18 @@ latex_documents = [
 # If false, no module index is generated.
 # latex_use_modindex = True
 
+# Register an autodoc class directive to only include exported methods.
+ClassDocumenter.option_spec['exported'] = bool_option
+
+
+def maybe_skip_member(app, what, name, obj, skip, options):
+    if options.exported and not (
+        hasattr(obj, '_rpcserver_export') or hasattr(obj, '_json_export')
+    ):
+        return True
+
 
 def setup(app):
-    app.add_config_value(
-        'recommonmark_config', {'auto_toc_tree_section': 'Contents'}, True
-    )
+    app.connect('autodoc-skip-member', maybe_skip_member)
+    app.add_config_value('recommonmark_config', {}, True)
     app.add_transform(AutoStructify)