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

Refactor docs to use ExDocs search_data model for global HexDocs indexing of Gleam packages #3904

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Prev Previous commit
Next Next commit
Refactor docs to not use abbreviated names of ExDocs search_data mode…
…l in Rust
  • Loading branch information
diemogebhardt committed Dec 24, 2024
commit cc0ba6f4815f2e9593a8ace7d4bff95d73894d8a
36 changes: 19 additions & 17 deletions compiler-core/src/docs.rs
Original file line number Diff line number Diff line change
Expand Up @@ -152,8 +152,8 @@ pub fn generate_html<IO: FileSystemReader>(
type_: SearchItemType::Page,
parent_title: config.name.to_string(),
title: config.name.to_string(),
doc: content,
ref_: page.path.to_string(),
content,
reference: page.path.to_string(),
})
}

Expand Down Expand Up @@ -218,50 +218,50 @@ pub fn generate_html<IO: FileSystemReader>(
type_: SearchItemType::Type,
parent_title: module.name.to_string(),
title: type_.name.to_string(),
doc: format!(
content: format!(
"{}\n{}\n{}\n{}",
type_.definition,
type_.text_documentation,
constructors,
import_synonyms(&module.name, type_.name)
),
ref_: format!("{}.html#{}", module.name, type_.name),
reference: format!("{}.html#{}", module.name, type_.name),
})
});
constants.iter().for_each(|constant| {
search_items.push(SearchItem {
type_: SearchItemType::Constant,
parent_title: module.name.to_string(),
title: constant.name.to_string(),
doc: format!(
content: format!(
"{}\n{}\n{}",
constant.definition,
constant.text_documentation,
import_synonyms(&module.name, constant.name)
),
ref_: format!("{}.html#{}", module.name, constant.name),
reference: format!("{}.html#{}", module.name, constant.name),
})
});
functions.iter().for_each(|function| {
search_items.push(SearchItem {
type_: SearchItemType::Function,
parent_title: module.name.to_string(),
title: function.name.to_string(),
doc: format!(
content: format!(
"{}\n{}\n{}",
function.signature,
function.text_documentation,
import_synonyms(&module.name, function.name)
),
ref_: format!("{}.html#{}", module.name, function.name),
reference: format!("{}.html#{}", module.name, function.name),
})
});
search_items.push(SearchItem {
type_: SearchItemType::Module,
parent_title: module.name.to_string(),
title: module.name.to_string(),
doc: documentation_content,
ref_: format!("{}.html", module.name),
content: documentation_content,
reference: format!("{}.html", module.name),
});

let page_title = format!("{} · {} · v{}", name, config.name, config.version);
Expand Down Expand Up @@ -372,7 +372,7 @@ pub fn generate_html<IO: FileSystemReader>(

let search_data_json = serde_to_string(&SearchData {
items: escape_html_contents(search_items),
proglang: SearchProgLang::Gleam,
programming_language: SearchProgrammingLanguage::Gleam,
})
.expect("search index serialization");

Expand Down Expand Up @@ -524,8 +524,8 @@ fn escape_html_contents(indexes: Vec<SearchItem>) -> Vec<SearchItem> {
type_: idx.type_,
parent_title: idx.parent_title,
title: idx.title,
doc: escape_html_content(idx.doc),
ref_: idx.ref_,
content: escape_html_content(idx.content),
reference: idx.reference,
})
.collect::<Vec<SearchItem>>()
}
Expand Down Expand Up @@ -839,7 +839,8 @@ struct ModuleTemplate<'a> {
#[derive(Serialize, PartialEq, Eq, PartialOrd, Ord, Clone)]
struct SearchData {
items: Vec<SearchItem>,
proglang: SearchProgLang,
#[serde(rename = "proglang")]
programming_language: SearchProgrammingLanguage,
}

#[derive(Serialize, PartialEq, Eq, PartialOrd, Ord, Clone)]
Expand All @@ -849,9 +850,10 @@ struct SearchItem {
#[serde(rename = "parentTitle")]
parent_title: String,
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you have an idea of how to name this better?

See comment regarding this below.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's a parent title? Could you add /// documentation comments for each of these fields pleaes

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please have a look at my comments above:

  • In one I pasted a screenshot to visualize how it's being used currently;
  • and in another asked whether you might have an idea for a better name?

Please also have a look at my Notes.

title: String,
doc: String,
#[serde(rename = "doc")]
content: String,
#[serde(rename = "ref")]
ref_: String,
reference: String,
}

#[derive(Serialize, PartialEq, Eq, PartialOrd, Ord, Clone)]
Expand All @@ -866,7 +868,7 @@ enum SearchItemType {

#[derive(Serialize, PartialEq, Eq, PartialOrd, Ord, Clone)]
#[serde(rename_all = "lowercase")]
enum SearchProgLang {
enum SearchProgrammingLanguage {
// Elixir,
// Erlang,
Gleam,
Expand Down
Loading