Remove a few other doc warnings (#1017)

* Remove a few other doc warnings

Handle model ambiguity by linking the closes one in the import try (v1
apis references v1 models for examples), and remove links inside
emphasis.

* Remove escaped space

Author: therve

.generator/src/generator/formatter.py

@@ -60,12 +60,14 @@ def attribute_path(attribute):
 class CustomRenderer(m2r2.RestRenderer):
     def double_emphasis(self, text):
         if "``" in text:
-            text = text.replace("\ ``", "").replace("``\ ", "")
-        return super().double_emphasis(text)
+            text = text.replace("\\ ``", "").replace("``\\ ", "")
+        if "`_" in text:
+            return text
+        return "\\ **{}**\\ ".format(text)
 
     def header(self, text, level, raw=None):
         return "\n{}\n".format(self.double_emphasis(text))
 
 
 def docstring(text):
-    return m2r2.convert(text.replace("\\n", "\\\\n"), renderer=CustomRenderer())[1:-1]
+    return m2r2.convert(text.replace("\\n", "\\\\n"), renderer=CustomRenderer())[1:-1].replace("\\ ", " ")

docs/conf.py

@@ -4,9 +4,12 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
+import difflib
 import os
 import sys
 
+from sphinx.domains.python import PythonDomain
+
 sys.path.insert(0, os.path.abspath("../src"))
 
 
@@ -73,3 +76,62 @@
 add_module_names = False
 
 autoclass_content = "both"
+
+
+def find_obj(domain, env, modname, classname, name, type, searchmode=0):
+    # skip parens
+    if name[-2:] == '()':
+        name = name[:-2]
+
+    if not name:
+        return []
+
+    matches = []
+
+    newname = None
+    if searchmode == 1:
+        if type is None:
+            objtypes = list(domain.object_types)
+        else:
+            objtypes = domain.objtypes_for_role(type)
+        if objtypes is not None:
+            if modname and classname:
+                fullname = modname + '.' + classname + '.' + name
+                if fullname in domain.objects and domain.objects[fullname].objtype in objtypes:
+                    newname = fullname
+            if not newname:
+                if modname and modname + '.' + name in domain.objects and \
+                   domain.objects[modname + '.' + name].objtype in objtypes:
+                    newname = modname + '.' + name
+                elif name in domain.objects and domain.objects[name].objtype in objtypes:
+                    newname = name
+                else:
+                    # "fuzzy" searching mode
+                    searchname = '.' + name
+                    matches = [(oname, domain.objects[oname]) for oname in domain.objects
+                               if oname.endswith(searchname) and
+                               domain.objects[oname].objtype in objtypes]
+                    if len(matches) > 1:
+                        close_match = difflib.get_close_matches(modname, [m[0] for m in matches], n=1, cutoff=0.1)
+                        if close_match:
+                            matches = [m for m in matches if m[0] == close_match[0]]
+    else:
+        # NOTE: searching for exact match, object type is not considered
+        if name in domain.objects:
+            newname = name
+        elif type == 'mod':
+            # only exact matches allowed for modules
+            return []
+        elif classname and classname + '.' + name in domain.objects:
+            newname = classname + '.' + name
+        elif modname and modname + '.' + name in domain.objects:
+            newname = modname + '.' + name
+        elif modname and classname and \
+                modname + '.' + classname + '.' + name in domain.objects:
+            newname = modname + '.' + classname + '.' + name
+    if newname is not None:
+        matches.append((newname, domain.objects[newname]))
+    return matches
+
+
+PythonDomain.find_obj = find_obj