Skip to content

Commit c87df70

Browse files
makspllmakspll
committed
fix more broken links and escape markdown better
1 parent 5bf2e68 commit c87df70

File tree

3 files changed

+35
-167
lines changed

3 files changed

+35
-167
lines changed

‎crates/lad_backends/mdbook_lad_preprocessor/src/markdown.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
use std::borrow::Cow;
22

3-
/// Takes the first n characters from the markdown, without splitting any formatting
3+
/// Takes the first n characters from the markdown, without splitting any formatting.
44
pub(crate) fn markdown_substring(markdown: &str, length: usize) -> &str {
55
if markdown.len() <= length {
66
return markdown;

‎crates/lad_backends/mdbook_lad_preprocessor/src/sections.rs

Lines changed: 21 additions & 166 deletions
Original file line numberDiff line numberDiff line change
@@ -10,148 +10,11 @@ use ladfile::{
1010
use mdbook::book::Chapter;
1111
use std::{borrow::Cow, collections::HashSet};
1212

13-
// pub(crate) fn section_to_chapter(
14-
// section: SectionAndChildren,
15-
// original_chapter: Option<&Chapter>,
16-
// parent_names: Vec<String>,
17-
// number: Option<SectionNumber>,
18-
// root_path: Option<PathBuf>,
19-
// root_source_path: Option<PathBuf>,
20-
// ) -> Chapter {
21-
// let mut parent_builder = MarkdownBuilder::new();
22-
// section.section.to_markdown(&mut parent_builder);
23-
24-
// // important to reset the extension of the parent, since when we're nesting
25-
// // we add the filename with .md, but if the parent is being emitted as markdown, then when
26-
// // we create the child, we will create the `parent.md` file as a folder, then when we emit
27-
// // the parent itself, the file (directory) will already exist
28-
// let new_path = root_path
29-
// .unwrap_or_default()
30-
// .with_extension("")
31-
// .join(section.section.file_name());
32-
33-
// let new_source_path = root_source_path
34-
// .unwrap_or_default()
35-
// .with_extension("")
36-
// .join(section.section.file_name());
37-
38-
// let current_number = number.clone().unwrap_or_default();
39-
40-
// let children_chapters = section
41-
// .children
42-
// .into_iter()
43-
// .enumerate()
44-
// .map(|(index, child)| {
45-
// let mut new_number = current_number.clone();
46-
// new_number.push(index as u32);
47-
// section_to_chapter(
48-
// child,
49-
// None,
50-
// vec![section.section.title()],
51-
// Some(new_number),
52-
// Some(new_path.clone()),
53-
// Some(new_source_path.clone()),
54-
// )
55-
// })
56-
// .map(mdbook::BookItem::Chapter)
57-
// .collect();
58-
59-
// if let Some(original) = original_chapter {
60-
// // override content only
61-
// log::debug!(
62-
// "Setting .md extension for chapter paths: {:?}, {:?}.",
63-
// original.path,
64-
// original.source_path
65-
// );
66-
67-
// Chapter {
68-
// content: parent_builder.build(),
69-
// sub_items: children_chapters,
70-
// path: original.path.as_ref().map(|p| p.with_extension("md")),
71-
// source_path: original
72-
// .source_path
73-
// .as_ref()
74-
// .map(|p| p.with_extension("md")),
75-
// ..original.clone()
76-
// }
77-
// } else {
78-
// Chapter {
79-
// name: section.section.title(),
80-
// content: parent_builder.build(),
81-
// number,
82-
// sub_items: children_chapters,
83-
// path: Some(new_path),
84-
// source_path: Some(new_source_path),
85-
// parent_names,
86-
// }
87-
// }
88-
// }
89-
90-
// fn section_to_section_and_children(section: Section<'_>) -> SectionAndChildren<'_> {
91-
// let children = section
92-
// .children()
93-
// .into_iter()
94-
// .map(section_to_section_and_children)
95-
// .collect();
96-
97-
// SectionAndChildren { children, section }
98-
// }
99-
100-
// pub(crate) fn lad_file_to_sections(
101-
// ladfile: &ladfile::LadFile,
102-
// title: Option<String>,
103-
// ) -> SectionAndChildren<'_> {
104-
// section_to_section_and_children(Section::Summary { ladfile, title })
105-
// build a hierarchy as follows:
106-
// - Summary
107-
// - Instances
108-
// - Functions
109-
// - Global Function Detail 1
110-
// - Types
111-
// - Type1
112-
// - Type detail 1
113-
// - Function detail 1
114-
// - Function detail 2
115-
// let mut types_children = ladfile
116-
// .types
117-
// .iter()
118-
// .map(|(_, lad_type)| (lad_type, Section::TypeDetail { lad_type, ladfile }))
119-
// .map(|(lad_type, section)| SectionAndChildren {
120-
// section,
121-
// children: lad_type
122-
// .associated_functions
123-
// .iter()
124-
// .filter_map(|f| {
125-
// let function = ladfile.functions.get(f)?;
126-
// Some(SectionAndChildren {
127-
// section: Section::FunctionDetail { function, ladfile },
128-
// children: vec![],
129-
// })
130-
// })
131-
// .collect(),
132-
// })
133-
// .collect();
134-
135-
// // now add a `functions` subsection before all types, for global functions
136-
137-
// SectionAndChildren {
138-
// section: summary,
139-
// children: vec![
140-
// SectionAndChildren {
141-
// section: Section::TypeSummary { ladfile },
142-
// children: types_children,
143-
// },
144-
// SectionAndChildren {
145-
// section: Section::FunctionSummary { ladfile },
146-
// children: vec![],
147-
// },
148-
// ],
149-
// }
150-
// }
151-
// pub(crate) struct SectionAndChildren<'a> {
152-
// section: Section<'a>,
153-
// children: Vec<SectionAndChildren<'a>>,
154-
// }
13+
fn print_type(ladfile: &LadFile, type_: &LadTypeId) -> String {
14+
let mut visitor = MarkdownArgumentVisitor::new(ladfile);
15+
visitor.visit_lad_type_id(type_);
16+
visitor.build()
17+
}
15518

15619
/// Sections which convert to single markdown files
15720
pub(crate) enum Section<'a> {
@@ -240,11 +103,7 @@ impl<'a> Section<'a> {
240103
ladfile,
241104
lad_type_id,
242105
..
243-
} => {
244-
let mut visitor = MarkdownArgumentVisitor::new(ladfile);
245-
visitor.visit_lad_type_id(lad_type_id);
246-
visitor.build()
247-
}
106+
} => print_type(ladfile, lad_type_id),
248107
Section::FunctionDetail { function, .. } => function.identifier.to_string(),
249108
}
250109
}
@@ -349,10 +208,11 @@ impl<'a> Section<'a> {
349208
vec![SectionItem::InstancesSummary { instances }]
350209
}
351210
Section::TypeSummary { ladfile } => {
352-
let types = ladfile.types.values().collect::<Vec<_>>();
211+
let types = ladfile.types.keys().collect::<Vec<_>>();
353212
vec![SectionItem::TypesSummary {
354213
types,
355214
types_directory: linkify_filename(self.title()),
215+
ladfile,
356216
}]
357217
}
358218
Section::FunctionSummary { ladfile } => {
@@ -432,8 +292,9 @@ pub enum SectionItem<'a> {
432292
ladfile: &'a ladfile::LadFile,
433293
},
434294
TypesSummary {
435-
types: Vec<&'a LadType>,
295+
types: Vec<&'a LadTypeId>,
436296
types_directory: String,
297+
ladfile: &'a ladfile::LadFile,
437298
},
438299
InstancesSummary {
439300
instances: Vec<(&'a Cow<'static, str>, &'a LadInstance)>,
@@ -529,7 +390,7 @@ impl IntoMarkdown for SectionItem<'_> {
529390
builder.row(markdown_vec![
530391
Markdown::new_paragraph(first_col).code(),
531392
Markdown::Link {
532-
text: second_col.to_owned(),
393+
text: second_col.to_owned().replace("\n", " "),
533394
url: format!("./{}/{}.md", functions_path, function.identifier),
534395
anchor: false
535396
}
@@ -540,36 +401,30 @@ impl IntoMarkdown for SectionItem<'_> {
540401
SectionItem::TypesSummary {
541402
types,
542403
types_directory,
404+
ladfile,
543405
} => {
544406
builder.heading(2, "Types");
545407

546408
// make a table of types as a quick reference, make them link to type details sub-sections
547409
builder.table(|builder| {
548410
builder.headers(vec!["Type", "Summary"]);
549411
for type_ in types.iter() {
550-
let first_col = type_.identifier.to_string();
412+
let printed_type = print_type(ladfile, type_);
413+
414+
let documentation = ladfile.get_type_documentation(type_);
551415

552416
// first line with content from documentation trimmed to 100 chars
553-
let second_col = type_
554-
.documentation
555-
.as_deref()
556-
.map(|doc| {
557-
let doc = doc.trim();
558-
if doc.len() > 100 {
559-
format!("{}...", &doc[..100])
560-
} else {
561-
doc.to_owned()
562-
}
563-
})
564-
.unwrap_or_else(|| NO_DOCS_STRING.to_owned());
417+
let second_col = documentation
418+
.map(|doc| markdown_substring(doc, 100))
419+
.unwrap_or_else(|| NO_DOCS_STRING);
565420

566421
builder.row(markdown_vec![
567-
Markdown::new_paragraph(first_col).code(),
422+
Markdown::new_paragraph(printed_type.clone()).code(),
568423
Markdown::Link {
569-
text: second_col,
424+
text: second_col.to_owned().replace("\n", " "),
570425
url: format!(
571426
"./{types_directory}/{}.md",
572-
linkify_filename(&type_.identifier)
427+
linkify_filename(printed_type)
573428
),
574429
anchor: false
575430
}

‎crates/ladfile/src/lib.rs

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,19 @@ impl LadFile {
6969
.get(type_id)
7070
.and_then(|t| (!t.generics.is_empty()).then_some(t.generics.as_slice()))
7171
}
72+
73+
/// Retrieves the documentation of a type id if it is a defined type and has documentation.
74+
pub fn get_type_documentation(&self, type_id: &LadTypeId) -> Option<&str> {
75+
self.types
76+
.get(type_id)
77+
.and_then(|t| t.documentation.as_deref())
78+
// try primitives
79+
.or_else(|| {
80+
self.primitives
81+
.get(type_id)
82+
.map(|p| p.documentation.as_ref())
83+
})
84+
}
7285
}
7386

7487
impl Default for LadFile {

0 commit comments

Comments
 (0)