documentation/python: make pybind11 compatibility opt-in.

This is becoming rather shitty.

diff --git a/doc/documentation/python.rst b/doc/documentation/python.rst
index 20b72a0f9e6c4c69639f3889ba8fd9259c20c578..2d070e577904ce2b60adf4a6fd60e86d313cc3b0 100644 (file)
--- a/doc/documentation/python.rst
+++ b/doc/documentation/python.rst
@@ -194,6 +194,11 @@ Variable                            Description
 :py:`CLASS_INDEX_EXPAND_INNER`      Whether to expand inner classes in the
                                     class index. If not set, :py:`False` is
                                     used.
+:py:`PYBIND11_COMPATIBILITY`        Enable some additional tricks for better
+                                    compatibility with pybind11. If not set,
+                                    :py:`False` is used. See
+                                    `pybind11 compatibility`_ for more
+                                    information.
 :py:`SEARCH_DISABLED: bool`         Disable search functionality. If this
                                     option is set, no search data is compiled
                                     and the rendered HTML does not contain
@@ -514,6 +519,15 @@ non-obvious way to document enum values as well.
 The documentation output for enums includes enum value values and the class it
 was derived from, so it's possible to know whether it's an enum or a flag.
 
+`pybind11 compatibility`_
+=========================
+
+C++ bindings generated using `pybind11 <https://pybind11.readthedocs.io/>`_ do
+not have all information accessible through introspection and thus the script
+has to do a few pybind11-specific workarounds to generate expected output. This
+behavior is not enabled by default as it *might* have unwanted consequences in
+pure Python code, enable it using the :py:`PYBIND11_COMPATIBILITY` option.
+
 `Command-line options`_
 =======================
 

diff --git a/documentation/python.py b/documentation/python.py
index d57addf39ca1760e663231b46ba112904a13144f..dfb4cbf8cf0a1f0a4318c89275867a709d2c5bf0 100755 (executable)
--- a/documentation/python.py
+++ b/documentation/python.py
@@ -71,6 +71,7 @@ default_config = {
     'FINE_PRINT': '[default]',
     'CLASS_INDEX_EXPAND_LEVELS': 1,
     'CLASS_INDEX_EXPAND_INNER': False,
+    'PYBIND11_COMPATIBILITY': False,
     'SEARCH_DISABLED': False,
     'SEARCH_DOWNLOAD_BINARY': False,
     'SEARCH_HELP': """.. raw:: html