From cc11a3fff37eb5c8a4d99773b2000e85f7617af0 Mon Sep 17 00:00:00 2001 From: Chenhao Zuo Date: Wed, 30 Oct 2024 13:43:44 -0700 Subject: [PATCH] Summary: Add a test for rendering the markdown with linked type in the signature. Reviewed By: JakobDegen Differential Revision: D65180323 fbshipit-source-id: 99d314b375493d517d055c9972cd32ad2a70b713 --- .../tests/golden/multipage/globals.golden.md | 2 +- .../tests/golden/multipage/submod.golden.md | 8 +++ .../multipage_linked_type/Magic.golden.md | 23 ++++++++ .../multipage_linked_type/Obj.golden.md | 52 +++++++++++++++++ .../multipage_linked_type/globals.golden.md | 56 +++++++++++++++++++ .../multipage_linked_type/submod.golden.md | 29 ++++++++++ .../src/docs/tests/golden/native.golden.md | 2 +- starlark/src/docs/tests/markdown.rs | 41 +++++++++++--- 8 files changed, 204 insertions(+), 9 deletions(-) create mode 100644 starlark/src/docs/tests/golden/multipage_linked_type/Magic.golden.md create mode 100644 starlark/src/docs/tests/golden/multipage_linked_type/Obj.golden.md create mode 100644 starlark/src/docs/tests/golden/multipage_linked_type/globals.golden.md create mode 100644 starlark/src/docs/tests/golden/multipage_linked_type/submod.golden.md diff --git a/starlark/src/docs/tests/golden/multipage/globals.golden.md b/starlark/src/docs/tests/golden/multipage/globals.golden.md index 5b78bc9cf..dd5d6fe81 100644 --- a/starlark/src/docs/tests/golden/multipage/globals.golden.md +++ b/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 ``` --- diff --git a/starlark/src/docs/tests/golden/multipage/submod.golden.md b/starlark/src/docs/tests/golden/multipage/submod.golden.md index dcfbb8ec0..6f8434d43 100644 --- a/starlark/src/docs/tests/golden/multipage/submod.golden.md +++ b/starlark/src/docs/tests/golden/multipage/submod.golden.md @@ -6,6 +6,14 @@ # submod +## new\_obj + +```python +def new_obj() -> obj +``` + +--- + ## notypes ```python diff --git a/starlark/src/docs/tests/golden/multipage_linked_type/Magic.golden.md b/starlark/src/docs/tests/golden/multipage_linked_type/Magic.golden.md new file mode 100644 index 000000000..6ccef1293 --- /dev/null +++ b/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 + +
def Magic(a1: int, a2: int = ..., step: int = 1, /) -> str
+ +A function with only positional arguments. + +And a slightly longer description. With some example code: + +```python +Magic(1) +``` + +And some assertions: + +```rust +1 == 1 +``` diff --git a/starlark/src/docs/tests/golden/multipage_linked_type/Obj.golden.md b/starlark/src/docs/tests/golden/multipage_linked_type/Obj.golden.md new file mode 100644 index 000000000..a72f94b0f --- /dev/null +++ b/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\_\_ + +
def Obj.__exported__() -> None
+ +Needs to be escaped when rendered in markdown. + +--- + +## Obj.attr1 + +
Obj.attr1: str
+ +Docs for attr1 + +--- + +## Obj.attr2 + +
Obj.attr2: str
+ +--- + +## Obj.func1 + +
def Obj.func1(foo: str) -> str
+ +Docs for func1 + +#### Parameters + +* `foo`: Docs for foo + + +#### Returns + +The string 'func1' + +--- + +## Obj.func2 + +
def Obj.func2() -> str
diff --git a/starlark/src/docs/tests/golden/multipage_linked_type/globals.golden.md b/starlark/src/docs/tests/golden/multipage_linked_type/globals.golden.md new file mode 100644 index 000000000..9f79fc13e --- /dev/null +++ b/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 + +
MAGIC: int
+ +--- + +## func1 + +
def func1(foo: str) -> str
+ +Docs for func1 + +#### Parameters + +* `foo`: Docs for foo + + +#### Returns + +The string 'func1' + +--- + +## func2 + +
def func2() -> str
+ +--- + +## pos\_either\_named + +
def pos_either_named(
+    a: int,
+    /,
+    b: int,
+    *,
+    c: int,
+) -> magic
+ +--- + +## with\_defaults + +
def with_defaults(
+    explicit_default: list[str] = [],
+    hidden_default: list[str] = ...,
+    string_default: str = "my_default",
+) -> None
diff --git a/starlark/src/docs/tests/golden/multipage_linked_type/submod.golden.md b/starlark/src/docs/tests/golden/multipage_linked_type/submod.golden.md new file mode 100644 index 000000000..f9c84cc15 --- /dev/null +++ b/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 + +
def new_obj() -> obj
+ +--- + +## notypes + +
def notypes(a)
+ +--- + +## starlark\_args + +
def starlark_args(*args: str) -> None
+ +--- + +## starlark\_kwargs + +
def starlark_kwargs(**kwargs: int) -> None
diff --git a/starlark/src/docs/tests/golden/native.golden.md b/starlark/src/docs/tests/golden/native.golden.md index 1ca82fc46..92fecb0d7 100644 --- a/starlark/src/docs/tests/golden/native.golden.md +++ b/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 ``` --- diff --git a/starlark/src/docs/tests/markdown.rs b/starlark/src/docs/tests/markdown.rs index d262eeb43..6a52a2dd6 100644 --- a/starlark/src/docs/tests/markdown.rs +++ b/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 { + ) -> anyhow::Result { 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 { + 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::>(), &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::();