Summary: Add a test for rendering the markdown with linked type in th…

…e signature.

Reviewed By: JakobDegen

Differential Revision: D65180323

fbshipit-source-id: 99d314b375493d517d055c9972cd32ad2a70b713

starlark/src/docs/tests/golden/multipage/globals.golden.md

@@ -44,7 +44,7 @@ def func2() -> str
 ## pos\_either\_named
 
 ```python
-def pos_either_named(a: int, /, b: int, *, c: int) -> None
+def pos_either_named(a: int, /, b: int, *, c: int) -> magic
 ```
 
 ---

starlark/src/docs/tests/golden/multipage/submod.golden.md

@@ -6,6 +6,14 @@
 
 # submod
 
+## new\_obj
+
+```python
+def new_obj() -> obj
+```
+
+---
+
 ## notypes
 
 ```python

starlark/src/docs/tests/golden/multipage_linked_type/Magic.golden.md

@@ -0,0 +1,23 @@
+# @generated
+# To regenerate, run:
+# ```
+# STARLARK_RUST_REGENERATE_GOLDEN_TESTS=1 cargo test -p starlark --lib
+# ```
+
+# Magic
+
+<pre class="language-python"><code>def Magic(a1: int, a2: int = ..., step: int = 1, /) -> str</code></pre>
+
+A function with only positional arguments.
+
+And a slightly longer description. With some example code:
+
+```python
+Magic(1)
+```
+
+And some assertions:
+
+```rust
+1 == 1
+```

starlark/src/docs/tests/golden/multipage_linked_type/Obj.golden.md

@@ -0,0 +1,52 @@
+# @generated
+# To regenerate, run:
+# ```
+# STARLARK_RUST_REGENERATE_GOLDEN_TESTS=1 cargo test -p starlark --lib
+# ```
+
+# Obj
+
+These are where the module docs go
+
+## Obj.\_\_exported\_\_
+
+<pre class="language-python"><code>def Obj.__exported__() -> None</code></pre>
+
+Needs to be escaped when rendered in markdown.
+
+---
+
+## Obj.attr1
+
+<pre class="language-python"><code>Obj.attr1: str</code></pre>
+
+Docs for attr1
+
+---
+
+## Obj.attr2
+
+<pre class="language-python"><code>Obj.attr2: str</code></pre>
+
+---
+
+## Obj.func1
+
+<pre class="language-python"><code>def Obj.func1(foo: str) -> str</code></pre>
+
+Docs for func1
+
+#### Parameters
+
+* `foo`: Docs for foo
+
+
+#### Returns
+
+The string 'func1'
+
+---
+
+## Obj.func2
+
+<pre class="language-python"><code>def Obj.func2() -> str</code></pre>

starlark/src/docs/tests/golden/multipage_linked_type/globals.golden.md

@@ -0,0 +1,56 @@
+# @generated
+# To regenerate, run:
+# ```
+# STARLARK_RUST_REGENERATE_GOLDEN_TESTS=1 cargo test -p starlark --lib
+# ```
+
+# globals
+
+## MAGIC
+
+<pre class="language-python"><code>MAGIC: int</code></pre>
+
+---
+
+## func1
+
+<pre class="language-python"><code>def func1(foo: str) -> str</code></pre>
+
+Docs for func1
+
+#### Parameters
+
+* `foo`: Docs for foo
+
+
+#### Returns
+
+The string 'func1'
+
+---
+
+## func2
+
+<pre class="language-python"><code>def func2() -> str</code></pre>
+
+---
+
+## pos\_either\_named
+
+<pre class="language-python"><code>def pos_either_named(
+    a: int,
+    /,
+    b: int,
+    *,
+    c: int,
+) -> <a href="/path/to/Magic">magic</a></code></pre>
+
+---
+
+## with\_defaults
+
+<pre class="language-python"><code>def with_defaults(
+    explicit_default: list[str] = [],
+    hidden_default: list[str] = ...,
+    string_default: str = "my_default",
+) -> None</code></pre>

starlark/src/docs/tests/golden/multipage_linked_type/submod.golden.md

@@ -0,0 +1,29 @@
+# @generated
+# To regenerate, run:
+# ```
+# STARLARK_RUST_REGENERATE_GOLDEN_TESTS=1 cargo test -p starlark --lib
+# ```
+
+# submod
+
+## new\_obj
+
+<pre class="language-python"><code>def new_obj() -> <a href="/path/to/Obj">obj</a></code></pre>
+
+---
+
+## notypes
+
+<pre class="language-python"><code>def notypes(a)</code></pre>
+
+---
+
+## starlark\_args
+
+<pre class="language-python"><code>def starlark_args(*args: str) -> None</code></pre>
+
+---
+
+## starlark\_kwargs
+
+<pre class="language-python"><code>def starlark_kwargs(**kwargs: int) -> None</code></pre>

starlark/src/docs/tests/golden/native.golden.md

@@ -62,7 +62,7 @@ def func2() -> str
 ## pos\_either\_named
 
 ```python
-def pos_either_named(a: int, /, b: int, *, c: int) -> None
+def pos_either_named(a: int, /, b: int, *, c: int) -> magic
 ```
 
 ---

starlark/src/docs/tests/markdown.rs

@@ -19,6 +19,7 @@ use allocative::Allocative;
 use derive_more::Display;
 use itertools::Itertools;
 use serde::Serialize;
+use starlark::starlark_simple_value;
 use starlark_derive::starlark_module;
 use starlark_derive::starlark_value;
 use starlark_derive::NoSerialize;
@@ -111,6 +112,8 @@ def _do_not_export():
 #[display("magic")]
 struct Magic;
 
+starlark_simple_value!(Magic);
+
 #[starlark_value(type = "magic")]
 impl<'v> StarlarkValue<'v> for Magic {}
 
@@ -175,9 +178,9 @@ fn module(builder: &mut GlobalsBuilder) {
         #[starlark(require = pos)] a: i32,
         b: i32,
         #[starlark(require = named)] c: i32,
-    ) -> anyhow::Result<NoneType> {
+    ) -> anyhow::Result<Magic> {
         let _unused = (a, b, c);
-        Ok(NoneType)
+        Ok(Magic)
     }
 }
 
@@ -198,6 +201,10 @@ fn submodule(builder: &mut GlobalsBuilder) {
         let _ignore = kwargs;
         Ok(NoneType)
     }
+
+    fn new_obj() -> anyhow::Result<Obj> {
+        Ok(Obj)
+    }
 }
 
 fn get_globals() -> Globals {
@@ -211,6 +218,8 @@ fn get_globals() -> Globals {
 #[display("obj")]
 struct Obj;
 
+starlark_simple_value!(Obj);
+
 #[starlark_value(type = "obj")]
 impl<'v> StarlarkValue<'v> for Obj {
     fn get_methods() -> Option<&'static Methods> {
@@ -276,27 +285,45 @@ fn native_docs_module() {
     assert!(res.contains(r#"string_default: str = "my_default"#));
 }
 
-#[test]
-fn globals_docs_render() {
+fn test_globals_docs_render(with_linked_type: bool) {
     let global = get_globals().documentation();
     let modules_info = DocModuleInfo {
         module: &global,
         name: "globals".to_owned(),
         page_path: "".to_owned(),
     };
-
-    let res = render_markdown_multipage(vec![modules_info], None);
+    let path_mapper = |p: &str| format!("/path/to/{}", p);
+    let res = if with_linked_type {
+        render_markdown_multipage(vec![modules_info], Some(&path_mapper))
+    } else {
+        render_markdown_multipage(vec![modules_info], None)
+    };
+    let subfolder_name = if with_linked_type {
+        "multipage_linked_type"
+    } else {
+        "multipage"
+    };
     let expected_keys = vec!["", "Magic", "Obj", "submod"];
     assert_eq!(&res.keys().sorted().collect::<Vec<_>>(), &expected_keys);
     for (k, v) in res {
         let k = if k.is_empty() { "globals" } else { &k };
         golden_test_template(
-            &format!("src/docs/tests/golden/multipage/{}.golden.md", k),
+            &format!("src/docs/tests/golden/{subfolder_name}/{}.golden.md", k),
             &v,
         );
     }
 }
 
+#[test]
+fn globals_docs_render() {
+    test_globals_docs_render(false);
+}
+
+#[test]
+fn globals_docs_render_with_linked_type() {
+    test_globals_docs_render(true);
+}
+
 #[test]
 fn golden_docs_object() {
     let docs = DocType::from_starlark_value::<Obj>();