documentation/python: show function values as ellipses as well, for now.

Putting `<function whatever>` into a Python stub file isn't a good idea
at all, as it's a syntax error. It isn't really useful for the HTML
output either because there's just the name, not the fully qualified
function, and it's not a link either.

I may eventually go back to this and make those actual names and links
if the functions are known, but right now there are other, more important
things left to do.

diff --git a/documentation/python.py b/documentation/python.py
index 3668d889eb5e0a0cbe90dacb33e60641dc636a31..775f5e5fcf4b35b96ca6304d7598f43e195bb737 100755 (executable)
--- a/documentation/python.py
+++ b/documentation/python.py
@@ -1095,8 +1095,12 @@ def format_value(state: State, referrer_path: List[str], value) -> Optional[Tupl
     elif state.config['PYBIND11_COMPATIBILITY'] and hasattr(value.__class__, '__members__'):
         # TODO Python 3.8+ supports `a, *b`, switch to that once 3.7 is dropped
         return (value.name, ) + make_name_relative_link(state, referrer_path, '{}.{}.{}'.format(value.__class__.__module__, value.__class__.__qualname__, value.name))
-    elif inspect.isfunction(value):
-        out = '<function {}>'.format(value.__name__)
+    # isbuiltin returns true if object is a builtin _function_ or _method_, not
+    # just any builtin such as the False literal
+    elif inspect.isfunction(value) or inspect.isbuiltin(value):
+        # TODO if the function is in our name map, return its name and link to
+        #   it maybe?
+        out = '...'
         return out, out, html.escape(out)
     elif '__repr__' in type(value).__dict__:
         rendered = repr(value)

diff --git a/documentation/test_python/content_html_escape/content_html_escape.html b/documentation/test_python/content_html_escape/content_html_escape.html
index b85681f5e5c2b0fc49c40d5cd5ee6d20cd686bc4..5d63da287297ba679de86ed931d02f30f2378058 100644 (file)
--- a/documentation/test_python/content_html_escape/content_html_escape.html
+++ b/documentation/test_python/content_html_escape/content_html_escape.html
@@ -78,8 +78,7 @@
           <h2><a href="#functions">Functions</a></h2>
           <dl class="m-doc">
             <dt id="function">
-              <span class="m-doc-wrap-bumper">def <a href="#function" class="m-doc-self">function</a>(</span><span class="m-doc-wrap">default_string_that_should_be_escaped = &#x27;&lt;&amp;&gt;&#x27;,
-              default_function_that_should_be_escaped = &lt;function &lt;lambda&gt;&gt;)</span>
+              <span class="m-doc-wrap-bumper">def <a href="#function" class="m-doc-self">function</a>(</span><span class="m-doc-wrap">default_string_that_should_be_escaped = &#x27;&lt;&amp;&gt;&#x27;)</span>
             </dt>
             <dd></dd>
           </dl>

diff --git a/documentation/test_python/content_html_escape/content_html_escape/__init__.py b/documentation/test_python/content_html_escape/content_html_escape/__init__.py
index dba885ebade8ffe73b0c051618966d2bbdd352e7..d51eedcea42540792d933ca4e4642f829eb6abee 100644 (file)
--- a/documentation/test_python/content_html_escape/content_html_escape/__init__.py
+++ b/documentation/test_python/content_html_escape/content_html_escape/__init__.py
@@ -33,7 +33,7 @@ class Class:
 class Enum(enum.Enum):
     VALUE_THAT_SHOULD_BE_ESCAPED = "<&>"
 
-def function(default_string_that_should_be_escaped = "<&>", default_function_that_should_be_escaped = lambda a: a):
+def function(default_string_that_should_be_escaped = "<&>"):
     pass
 
 DATA_THAT_SHOULD_BE_ESCAPED = "<&>"

diff --git a/documentation/test_python/inspect_value_formatting/inspect_value_formatting.html b/documentation/test_python/inspect_value_formatting/inspect_value_formatting.html
index e9f6c3684f206860ef971904274165847c05c6e1..2e7c0a7ad839efacb0747caf7b711b4c99f541bf 100644 (file)
--- a/documentation/test_python/inspect_value_formatting/inspect_value_formatting.html
+++ b/documentation/test_python/inspect_value_formatting/inspect_value_formatting.html
@@ -64,7 +64,9 @@
             </dt>
             <dd></dd>
             <dt id="setup_callback">
-              <span class="m-doc-wrap-bumper">def <a href="#setup_callback" class="m-doc-self">setup_callback</a>(</span><span class="m-doc-wrap">callback = &lt;function basics&gt;)</span>
+              <span class="m-doc-wrap-bumper">def <a href="#setup_callback" class="m-doc-self">setup_callback</a>(</span><span class="m-doc-wrap">unknown_function_is_an_ellipsis = ...,
+              builtin_function_is_an_ellipsis = ...,
+              lambda_is_an_ellipsis = ...)</span>
             </dt>
             <dd>Should produce a deterministic output.</dd>
           </dl>

diff --git a/documentation/test_python/inspect_value_formatting/inspect_value_formatting.py b/documentation/test_python/inspect_value_formatting/inspect_value_formatting.py
index d4ccdb2684a5f5e83254c4ce52c9c10c225a8379..621f36e0010ffb8cc1a59e1e5983fa7d4ad08f2f 100644 (file)
--- a/documentation/test_python/inspect_value_formatting/inspect_value_formatting.py
+++ b/documentation/test_python/inspect_value_formatting/inspect_value_formatting.py
@@ -1,6 +1,8 @@
 """Value and default argument formatting"""
 
 import enum
+import math
+import os
 
 class Foo:
     ...
@@ -8,7 +10,9 @@ class Foo:
 def basics(string_param = "string", tuple_param = (3, 5), float_param = 1.2, unrepresentable_param = Foo()):
     pass
 
-def setup_callback(callback = basics):
+def setup_callback(unknown_function_is_an_ellipsis = os.path.join,
+                   builtin_function_is_an_ellipsis = math.log,
+                   lambda_is_an_ellipsis = lambda a: a):
     """Should produce a deterministic output."""
     pass