Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve docs for TextDocument example #4008

Merged
merged 17 commits into from
Oct 26, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ namespace rerun.archetypes;
///
/// Supports raw text and markdown.
///
/// \example text_document !api title="Markdown text document" image="https://static.rerun.io/textdocument/babda19558ee32ed8d730495b595aee7a5e2c174/1200w.png"
/// \example text_document title="Markdown text document" image="https://static.rerun.io/textdocument/babda19558ee32ed8d730495b595aee7a5e2c174/1200w.png"
table TextDocument (
"attr.rust.derive": "PartialEq, Eq"
) {
Expand Down
69 changes: 69 additions & 0 deletions crates/re_types/src/archetypes/text_document.rs

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 4 additions & 0 deletions crates/re_types_builder/src/codegen/cpp/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2068,6 +2068,10 @@ fn lines_from_docs(docs: &Docs) -> Vec<String> {
..
} = &example.base;

for line in &example.lines {
assert!(!line.contains("```"), "Example {name:?} contains ``` in it, so we can't embed it in the C++ API docs.");
}
Wumpf marked this conversation as resolved.
Show resolved Hide resolved

if let Some(title) = title {
lines.push(format!("### {title}"));
} else {
Expand Down
10 changes: 8 additions & 2 deletions crates/re_types_builder/src/codegen/docs/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -192,7 +192,11 @@ fn object_page(reporter: &Reporter, object: &Object, object_map: &ObjectMap) ->
putln!(page);
write_used_by(&mut page, reporter, object, object_map);
}
ObjectKind::Blueprint | ObjectKind::Archetype => {}
ObjectKind::Blueprint | ObjectKind::Archetype => {
if examples.is_empty() {
reporter.warn(&object.virtpath, &object.fqname, "No examples");
}
}
}

page
Expand Down Expand Up @@ -259,7 +263,9 @@ fn write_used_by(o: &mut String, reporter: &Reporter, object: &Object, object_ma
// reference other tables, but they are unwrapped in the codegen.
// So for instance: `union Angle` uses `rerun.datatypes.Float32` in
// `angle.fbs`, but in the generated code that datatype is unused.
reporter.warn(&object.virtpath, &object.fqname, "Unused object");
if false {
reporter.warn(&object.virtpath, &object.fqname, "Unused object");
}
} else {
putln!(o, "## Used by");
putln!(o);
Expand Down
37 changes: 36 additions & 1 deletion crates/re_types_builder/src/codegen/python.rs
Original file line number Diff line number Diff line change
Expand Up @@ -875,13 +875,41 @@ fn quote_examples(examples: Vec<Example<'_>>, lines: &mut Vec<String>) {
name, title, image, ..
} = &example.base;

let mut example_lines = example.lines.clone();

if let Some(first_line) = example_lines.first() {
if first_line.starts_with("\"\"\"")
&& first_line.ends_with("\"\"\"")
&& first_line.len() > 6
{
// Remove one-line docstring, otherwise we can't embed this.
example_lines.remove(0);
}
}

// Remove leading blank lines:
while example_lines.first() == Some(&String::default()) {
example_lines.remove(0);
}

for line in &example_lines {
assert!(
!line.contains("```"),
"Example {name:?} contains ``` in it, so we can't embed it in the Python API docs."
);
assert!(
!line.contains("\"\"\""),
"Example {name:?} contains \"\"\" in it, so we can't embed it in the Python API docs."
);
}

if let Some(title) = title {
lines.push(format!("### {title}:"));
} else {
lines.push(format!("### `{name}`:"));
}
lines.push("```python".into());
lines.extend(example.lines.into_iter());
lines.extend(example_lines.into_iter());
lines.push("```".into());
if let Some(image) = &image {
lines.extend(image.image_stack());
Expand Down Expand Up @@ -930,6 +958,13 @@ fn quote_doc_lines(lines: Vec<String>) -> String {
return String::new();
}

for line in &lines {
assert!(
!line.contains("\"\"\""),
"Cannot put triple quotes in Python docstrings"
);
}

// NOTE: Filter out docstrings within docstrings, it just gets crazy otherwise…
let lines: Vec<String> = lines
.into_iter()
Expand Down
45 changes: 41 additions & 4 deletions crates/re_types_builder/src/codegen/rust/api.rs
Original file line number Diff line number Diff line change
Expand Up @@ -452,7 +452,14 @@ impl quote::ToTokens for ObjectFieldTokenizer<'_> {
}

fn quote_field_docs(reporter: &Reporter, field: &ObjectField) -> TokenStream {
let lines = doc_as_lines(reporter, &field.virtpath, &field.fqname, &field.docs);
let require_example = false;
let lines = doc_as_lines(
reporter,
&field.virtpath,
&field.fqname,
&field.docs,
require_example,
);

let require_field_docs = false;
if require_field_docs && lines.is_empty() && !field.is_testing() {
Expand All @@ -463,7 +470,14 @@ fn quote_field_docs(reporter: &Reporter, field: &ObjectField) -> TokenStream {
}

fn quote_obj_docs(reporter: &Reporter, obj: &Object) -> TokenStream {
let mut lines = doc_as_lines(reporter, &obj.virtpath, &obj.fqname, &obj.docs);
let require_example = obj.kind == ObjectKind::Archetype;
let mut lines = doc_as_lines(
reporter,
&obj.virtpath,
&obj.fqname,
&obj.docs,
require_example,
);

// Prefix first line with `**Datatype**: ` etc:
if let Some(first) = lines.first_mut() {
Expand All @@ -475,14 +489,24 @@ fn quote_obj_docs(reporter: &Reporter, obj: &Object) -> TokenStream {
quote_doc_lines(&lines)
}

fn doc_as_lines(reporter: &Reporter, virtpath: &str, fqname: &str, docs: &Docs) -> Vec<String> {
fn doc_as_lines(
reporter: &Reporter,
virtpath: &str,
fqname: &str,
docs: &Docs,
require_example: bool,
) -> Vec<String> {
let mut lines = crate::codegen::get_documentation(docs, &["rs", "rust"]);

let examples = collect_examples_for_api_docs(docs, "rs", true)
.map_err(|err| reporter.error(virtpath, fqname, err))
.unwrap_or_default();

if !examples.is_empty() {
if examples.is_empty() {
if require_example {
reporter.warn(virtpath, fqname, "Missing example");
}
} else {
lines.push(Default::default());
let section_title = if examples.len() == 1 {
"Example"
Expand All @@ -497,14 +521,27 @@ fn doc_as_lines(reporter: &Reporter, virtpath: &str, fqname: &str, docs: &Docs)
name, title, image, ..
} = &example.base;

for line in &example.lines {
if line.contains("```") {
reporter.error(
virtpath,
fqname,
format!("Example {name:?} contains ``` in it, so we can't embed it in the Rust API docs."),
);
continue;
}
}

if let Some(title) = title {
lines.push(format!("### {title}"));
} else {
lines.push(format!("### `{name}`:"));
}

lines.push("```ignore".into());
lines.extend(example.lines.into_iter());
lines.push("```".into());

if let Some(image) = &image {
lines.extend(image.image_stack().into_iter());
}
Expand Down
7 changes: 0 additions & 7 deletions docs/code-examples/text_document.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -29,13 +29,6 @@ Basic formatting:

----------------------------------

Some code:
```rs
fn main() {
println!("Hello, world!");
}
```

## Support
- [x] [Commonmark](https://commonmark.org/help/) support
- [x] GitHub-style strikethrough, tables, and checkboxes
Expand Down
12 changes: 2 additions & 10 deletions docs/code-examples/text_document.py
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
#!/usr/bin/env python3
"""Log a `TextDocument`."""

import rerun as rr
Expand All @@ -10,7 +9,7 @@
rr.log(
"markdown",
rr.TextDocument(
"""
'''
# Hello Markdown!
[Click here to see the raw text](recording://markdown.Text).

Expand All @@ -26,13 +25,6 @@

----------------------------------

Some code:
```rs
fn main() {
println!("Hello, world!");
}
```

## Support
- [x] [Commonmark](https://commonmark.org/help/) support
- [x] GitHub-style strikethrough, tables, and checkboxes
Expand All @@ -51,7 +43,7 @@

## Image
![A random image](https://picsum.photos/640/480)
""".strip(),
'''.strip(),
media_type=rr.MediaType.MARKDOWN,
),
)
7 changes: 0 additions & 7 deletions docs/code-examples/text_document.rs
Original file line number Diff line number Diff line change
Expand Up @@ -28,13 +28,6 @@ Basic formatting:

----------------------------------

Some code:
```rs
fn main() {
println!("Hello, world!");
}
```

## Support
- [x] [Commonmark](https://commonmark.org/help/) support
- [x] GitHub-style strikethrough, tables, and checkboxes
Expand Down
56 changes: 56 additions & 0 deletions rerun_cpp/src/rerun/archetypes/text_document.hpp

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading
Loading