documentation/python: add a NAME_MAPPING config option.

diff --git a/doc/documentation/python.rst b/doc/documentation/python.rst
index cfba339bd662dead56ee33245792f62c65a715ce..cdd1a4c3d28e894287ebf59ffdf459520b29c72b 100644 (file)
--- a/doc/documentation/python.rst
+++ b/doc/documentation/python.rst
@@ -217,6 +217,9 @@ Variable                            Description
 :py:`CLASS_INDEX_EXPAND_INNER`      Whether to expand inner classes in the
                                     class index. If not set, :py:`False` is
                                     used.
+:py:`NAME_MAPPING: Dict[str, str]`  Additional name mapping in addition to
+                                    what's figured out from the ``__all__``
+                                    members
 :py:`PYBIND11_COMPATIBILITY: bool`  Enable some additional tricks for better
                                     compatibility with pybind11. If not set,
                                     :py:`False` is used. See
@@ -440,13 +443,14 @@ the parent package. If a module's :py:`__package__` is empty, it's assumed to
 be a plain module (instead of a package) and since those can't have submodules,
 all found submodules in it are ignored.
 
-.. block-success:: Overriding the set of included names
+.. block-success:: Overriding the set of included names, module reorganization
 
-    In case the autodetection includes more than you want or you need to
-    include names from other modules as part of the module you need, you can
-    temporarily override the :py:`__all__` attribute when generating the docs.
-    For example, the following will list just the :py:`pow()` and :py:`log()`
-    funtions from the :py:`math` module, ignoring the rest:
+    In case the autodetection includes more than you want or, conversely, you
+    need to include names that would otherwise be excluded (such as underscored
+    names), you can temporarily override the :py:`__all__` attribute when
+    generating the docs. For example, the following will list just the
+    :py:`pow()` and :py:`log()` funtions from the :py:`math` module, ignoring
+    the rest:
 
     .. code:: py
 
@@ -455,6 +459,34 @@ all found submodules in it are ignored.
 
         INPUT_MODULES = [math]
 
+    In other cases, especially when native modules are involved, the inspected
+    name locations might not be what you want. By putting the names into
+    :py:`__all__` you tell the script it should map the inspected location to
+    the one provided. Note you should also hide the original location from the
+    script to avoid duplicate definitons (unless it's underscored, in which
+    case it'll get ignored automatically).
+
+    .. code:: py
+
+        # module math
+
+        from _native_math import fast_sin as sin
+        from _native_math import fast_cos as cos
+        __all__ = ['sin', 'cos']
+
+    Additionally, for mapping types of external libraries where the
+    autodetection from :py:`__all__` can't be performed, you can use the
+    :py:`NAME_MAPPING` option:
+
+    .. code:: py
+
+        NAME_MAPPING = {
+            'fastmath._native.Vector3': 'fastmath.Vector3',
+            'fastmath._native.Quaternion': 'fastmath.Quaternion',
+            # or, equivalently, if the mapping is the same for all members:
+            'fastmath._native': 'fastmath'
+        }
+
 `Docstrings`_
 -------------
 

diff --git a/documentation/python.py b/documentation/python.py
index 4642f19fb0ee6b4edc8e2187a2723dc898b7b17b..300e8cfccdab79ab3887ac9ce63c6d5c9fe9b975 100755 (executable)
--- a/documentation/python.py
+++ b/documentation/python.py
@@ -147,6 +147,7 @@ default_config = {
     'CLASS_INDEX_EXPAND_LEVELS': 1,
     'CLASS_INDEX_EXPAND_INNER': False,
 
+    'NAME_MAPPING': {},
     'PYBIND11_COMPATIBILITY': False,
     'ATTRS_COMPATIBILITY': False,
 
@@ -175,7 +176,7 @@ default_config = {
 class State:
     def __init__(self, config):
         self.config = config
-        self.name_mapping: Dict[str, str] = {}
+        self.name_mapping: Dict[str, str] = copy.deepcopy(config['NAME_MAPPING'])
         self.module_docs: Dict[str, Dict[str, str]] = {}
         self.class_docs: Dict[str, Dict[str, str]] = {}
         self.enum_docs: Dict[str, Dict[str, str]] = {}

diff --git a/documentation/test_python/inspect_name_mapping/inspect_name_mapping.submodule.html b/documentation/test_python/inspect_name_mapping/inspect_name_mapping.submodule.html
index 1a7319053042cbba58f3d869210db567bd11460b..824fcb2dcee5b41dcef6382ac40e505ecbfb0b03 100644 (file)
--- a/documentation/test_python/inspect_name_mapping/inspect_name_mapping.submodule.html
+++ b/documentation/test_python/inspect_name_mapping/inspect_name_mapping.submodule.html
@@ -39,7 +39,7 @@
           <dl class="m-doc">
             <dt id="foo">
               <span class="m-doc-wrap-bumper">def <a href="#foo" class="m-doc-self">foo</a>(</span><span class="m-doc-wrap">a: <a href="inspect_name_mapping.Class.html" class="m-doc">Class</a>,
-              b: int) -&gt; int</span>
+              b: int) -&gt; yay.ThisGotOverridenExternally</span>
             </dt>
             <dd>A function</dd>
           </dl>

diff --git a/documentation/test_python/inspect_name_mapping/inspect_name_mapping/_sub/bar.py b/documentation/test_python/inspect_name_mapping/inspect_name_mapping/_sub/bar.py
index 3c24d53baa3198abd7a46cf4ec5556af4128a152..5448b5ab79fc4eb19dc15e4c33a9cbb6f767833c 100644 (file)
--- a/documentation/test_python/inspect_name_mapping/inspect_name_mapping/_sub/bar.py
+++ b/documentation/test_python/inspect_name_mapping/inspect_name_mapping/_sub/bar.py
@@ -2,6 +2,9 @@
 
 from . import Foo
 
-def foo(a: Foo, b: int) -> int:
+class _NameThatGetsOverridenExternally:
+    pass
+
+def foo(a: Foo, b: int) -> _NameThatGetsOverridenExternally:
     """A function"""
     return b*2

diff --git a/documentation/test_python/test_inspect.py b/documentation/test_python/test_inspect.py
index 4a88a3a58e5aa1c7360c8d925aaba9710d553d7e..6651b39071029a7c81de897f2c8651e0e5f860c4 100644 (file)
--- a/documentation/test_python/test_inspect.py
+++ b/documentation/test_python/test_inspect.py
@@ -146,7 +146,11 @@ class Annotations(BaseInspectTestCase):
 
 class NameMapping(BaseInspectTestCase):
     def test(self):
-        self.run_python()
+        self.run_python({
+            'NAME_MAPPING': {
+                'inspect_name_mapping._sub.bar._NameThatGetsOverridenExternally': 'yay.ThisGotOverridenExternally'
+            }
+        })
         self.assertEqual(*self.actual_expected_contents('inspect_name_mapping.html'))
         self.assertEqual(*self.actual_expected_contents('inspect_name_mapping.Class.html'))
         self.assertEqual(*self.actual_expected_contents('inspect_name_mapping.submodule.html'))