From: Vladimír Vondruš Date: Fri, 30 Aug 2019 17:10:51 +0000 (+0200) Subject: documentation/python: add a NAME_MAPPING config option. X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=fde61546f7701b9330db111692cadcc22415127e;p=blog.git documentation/python: add a NAME_MAPPING config option. --- diff --git a/doc/documentation/python.rst b/doc/documentation/python.rst index cfba339b..cdd1a4c3 100644 --- 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 4642f19f..300e8cfc 100755 --- 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 1a731905..824fcb2d 100644 --- 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 @@
def foo(a: Class, - b: int) -> int + b: int) -> yay.ThisGotOverridenExternally
A function
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 3c24d53b..5448b5ab 100644 --- 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 4a88a3a5..6651b390 100644 --- 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'))