summaryrefslogtreecommitdiff
path: root/crates/typst-docs/src
diff options
context:
space:
mode:
Diffstat (limited to 'crates/typst-docs/src')
-rw-r--r--crates/typst-docs/src/html.rs238
-rw-r--r--crates/typst-docs/src/lib.rs1010
-rw-r--r--crates/typst-docs/src/link.rs102
-rw-r--r--crates/typst-docs/src/model.rs170
4 files changed, 749 insertions, 771 deletions
diff --git a/crates/typst-docs/src/html.rs b/crates/typst-docs/src/html.rs
index bde69d89..c64649e3 100644
--- a/crates/typst-docs/src/html.rs
+++ b/crates/typst-docs/src/html.rs
@@ -1,17 +1,22 @@
+use std::fmt::{self, Debug, Formatter};
use std::ops::Range;
use comemo::Prehashed;
+use ecow::EcoString;
+use heck::{ToKebabCase, ToTitleCase};
use pulldown_cmark as md;
+use serde::{Deserialize, Serialize};
use typed_arena::Arena;
-use typst::diag::FileResult;
-use typst::eval::{Bytes, Datetime, Tracer};
+use typst::diag::{FileResult, StrResult};
+use typst::eval::{Bytes, Datetime, Library, Tracer};
use typst::font::{Font, FontBook};
-use typst::geom::{Point, Size};
+use typst::geom::{Abs, Point, Size};
use typst::syntax::{FileId, Source, VirtualPath};
use typst::World;
+use unscanny::Scanner;
use yaml_front_matter::YamlFrontMatter;
-use super::*;
+use super::{contributors, OutlineItem, Resolver, FILE_DIR, FONTS, LIBRARY};
/// HTML documentation.
#[derive(Serialize)]
@@ -21,7 +26,7 @@ pub struct Html {
#[serde(skip)]
md: String,
#[serde(skip)]
- description: Option<String>,
+ description: Option<EcoString>,
#[serde(skip)]
outline: Vec<OutlineItem>,
}
@@ -39,18 +44,7 @@ impl Html {
/// Convert markdown to HTML.
#[track_caller]
- pub fn markdown(resolver: &dyn Resolver, md: &str) -> Self {
- Self::markdown_with_id_base(resolver, md, "")
- }
-
- /// Convert markdown to HTML, preceding all fragment identifiers with the
- /// `id_base`.
- #[track_caller]
- pub fn markdown_with_id_base(
- resolver: &dyn Resolver,
- md: &str,
- id_base: &str,
- ) -> Self {
+ pub fn markdown(resolver: &dyn Resolver, md: &str, nesting: Option<usize>) -> Self {
let mut text = md;
let mut description = None;
let document = YamlFrontMatter::parse::<Metadata>(md);
@@ -62,9 +56,18 @@ impl Html {
let options = md::Options::ENABLE_TABLES | md::Options::ENABLE_HEADING_ATTRIBUTES;
let ids = Arena::new();
- let mut handler = Handler::new(resolver, id_base.into(), &ids);
- let iter = md::Parser::new_ext(text, options)
- .filter_map(|mut event| handler.handle(&mut event).then_some(event));
+ let mut handler = Handler::new(text, resolver, nesting, &ids);
+ let mut events = md::Parser::new_ext(text, options).peekable();
+ let iter = std::iter::from_fn(|| loop {
+ let mut event = events.next()?;
+ handler.peeked = events.peek().and_then(|event| match event {
+ md::Event::Text(text) => Some(text.clone()),
+ _ => None,
+ });
+ if handler.handle(&mut event) {
+ return Some(event);
+ }
+ });
let mut raw = String::new();
md::html::push_html(&mut raw, iter);
@@ -93,7 +96,11 @@ impl Html {
/// Returns `None` if the HTML doesn't start with an `h1` tag.
pub fn title(&self) -> Option<&str> {
let mut s = Scanner::new(&self.raw);
- s.eat_if("<h1>").then(|| s.eat_until("</h1>"))
+ s.eat_if("<h1").then(|| {
+ s.eat_until('>');
+ s.eat_if('>');
+ s.eat_until("</h1>")
+ })
}
/// The outline of the HTML.
@@ -102,7 +109,7 @@ impl Html {
}
/// The description from the front matter.
- pub fn description(&self) -> Option<String> {
+ pub fn description(&self) -> Option<EcoString> {
self.description.clone()
}
}
@@ -116,26 +123,35 @@ impl Debug for Html {
/// Front matter metadata.
#[derive(Deserialize)]
struct Metadata {
- description: String,
+ description: EcoString,
}
struct Handler<'a> {
+ text: &'a str,
resolver: &'a dyn Resolver,
- lang: Option<String>,
- code: String,
+ peeked: Option<md::CowStr<'a>>,
+ lang: Option<EcoString>,
+ code: EcoString,
outline: Vec<OutlineItem>,
- id_base: String,
+ nesting: Option<usize>,
ids: &'a Arena<String>,
}
impl<'a> Handler<'a> {
- fn new(resolver: &'a dyn Resolver, id_base: String, ids: &'a Arena<String>) -> Self {
+ fn new(
+ text: &'a str,
+ resolver: &'a dyn Resolver,
+ nesting: Option<usize>,
+ ids: &'a Arena<String>,
+ ) -> Self {
Self {
+ text,
resolver,
+ peeked: None,
lang: None,
- code: String::new(),
+ code: EcoString::new(),
outline: vec![],
- id_base,
+ nesting,
ids,
}
}
@@ -157,15 +173,13 @@ impl<'a> Handler<'a> {
}
// Register HTML headings for the outline.
- md::Event::Start(md::Tag::Heading(level, Some(id), _)) => {
+ md::Event::Start(md::Tag::Heading(level, id, _)) => {
self.handle_heading(id, level);
}
// Also handle heading closings.
- md::Event::End(md::Tag::Heading(level, Some(_), _)) => {
- if *level > md::HeadingLevel::H1 && !self.id_base.is_empty() {
- nest_heading(level);
- }
+ md::Event::End(md::Tag::Heading(level, _, _)) => {
+ nest_heading(level, self.nesting());
}
// Rewrite contributor sections.
@@ -185,10 +199,10 @@ impl<'a> Handler<'a> {
"unsupported link type: {ty:?}",
);
- *dest = self
- .handle_link(dest)
- .unwrap_or_else(|| panic!("invalid link: {dest}"))
- .into();
+ *dest = match self.handle_link(dest) {
+ Ok(link) => link.into(),
+ Err(err) => panic!("invalid link: {dest} ({err})"),
+ };
}
// Inline raw.
@@ -208,7 +222,7 @@ impl<'a> Handler<'a> {
// Code blocks.
md::Event::Start(md::Tag::CodeBlock(md::CodeBlockKind::Fenced(lang))) => {
self.lang = Some(lang.as_ref().into());
- self.code = String::new();
+ self.code = EcoString::new();
return false;
}
md::Event::End(md::Tag::CodeBlock(md::CodeBlockKind::Fenced(_))) => {
@@ -232,7 +246,7 @@ impl<'a> Handler<'a> {
}
fn handle_image(&self, link: &str) -> String {
- if let Some(file) = FILES.get_file(link) {
+ if let Some(file) = FILE_DIR.get_file(link) {
self.resolver.image(link, file.contents())
} else if let Some(url) = self.resolver.link(link) {
url
@@ -241,16 +255,35 @@ impl<'a> Handler<'a> {
}
}
- fn handle_heading(&mut self, id: &mut &'a str, level: &mut md::HeadingLevel) {
+ fn handle_heading(
+ &mut self,
+ id_slot: &mut Option<&'a str>,
+ level: &mut md::HeadingLevel,
+ ) {
+ nest_heading(level, self.nesting());
if *level == md::HeadingLevel::H1 {
return;
}
+ let default = self.peeked.as_ref().map(|text| text.to_kebab_case());
+ let id: &'a str = match (&id_slot, default) {
+ (Some(id), default) => {
+ if Some(*id) == default.as_deref() {
+ eprintln!("heading id #{id} was specified unnecessarily");
+ }
+ id
+ }
+ (None, Some(default)) => self.ids.alloc(default).as_str(),
+ (None, None) => panic!("missing heading id {}", self.text),
+ };
+
+ *id_slot = (!id.is_empty()).then_some(id);
+
// Special case for things like "v0.3.0".
let name = if id.starts_with('v') && id.contains('.') {
- id.to_string()
+ id.into()
} else {
- id.to_title_case()
+ id.to_title_case().into()
};
let mut children = &mut self.outline;
@@ -262,106 +295,22 @@ impl<'a> Handler<'a> {
depth -= 1;
}
- // Put base before id.
- if !self.id_base.is_empty() {
- nest_heading(level);
- *id = self.ids.alloc(format!("{}-{id}", self.id_base)).as_str();
- }
-
- children.push(OutlineItem { id: id.to_string(), name, children: vec![] });
+ children.push(OutlineItem { id: id.into(), name, children: vec![] });
}
- fn handle_link(&self, link: &str) -> Option<String> {
- if link.starts_with('#') || link.starts_with("http") {
- return Some(link.into());
+ fn handle_link(&self, link: &str) -> StrResult<String> {
+ if let Some(link) = self.resolver.link(link) {
+ return Ok(link);
}
- if !link.starts_with('$') {
- return self.resolver.link(link);
- }
-
- let root = link.split('/').next()?;
- let rest = &link[root.len()..].trim_matches('/');
- let base = match root {
- "$tutorial" => "/docs/tutorial/",
- "$reference" => "/docs/reference/",
- "$category" => "/docs/reference/",
- "$syntax" => "/docs/reference/syntax/",
- "$styling" => "/docs/reference/styling/",
- "$scripting" => "/docs/reference/scripting/",
- "$types" => "/docs/reference/types/",
- "$type" => "/docs/reference/types/",
- "$func" => "/docs/reference/",
- "$guides" => "/docs/guides/",
- "$packages" => "/docs/packages/",
- "$changelog" => "/docs/changelog/",
- "$community" => "/docs/community/",
- _ => panic!("unknown link root: {root}"),
- };
-
- let mut route = base.to_string();
- if root == "$type" && rest.contains('.') {
- let mut parts = rest.split('.');
- let ty = parts.next()?;
- let method = parts.next()?;
- route.push_str(ty);
- route.push_str("/#methods-");
- route.push_str(method);
- } else if root == "$func" {
- let mut parts = rest.split('.').peekable();
- let first = parts.peek().copied();
- let mut focus = &LIBRARY.global;
- while let Some(m) = first.and_then(|name| module(focus, name).ok()) {
- focus = m;
- parts.next();
- }
-
- let name = parts.next()?;
-
- let value = focus.get(name).ok()?;
- let Value::Func(func) = value else { return None };
- let info = func.info()?;
- route.push_str(info.category);
- route.push('/');
-
- if let Some(group) = GROUPS
- .iter()
- .filter(|_| first == Some("math"))
- .find(|group| group.functions.iter().any(|func| func == info.name))
- {
- route.push_str(&group.name);
- route.push_str("/#");
- route.push_str(info.name);
- if let Some(param) = parts.next() {
- route.push_str("-parameters-");
- route.push_str(param);
- }
- } else {
- route.push_str(name);
- route.push('/');
- if let Some(next) = parts.next() {
- if info.params.iter().any(|param| param.name == next) {
- route.push_str("#parameters-");
- route.push_str(next);
- } else if info.scope.iter().any(|(name, _)| name == next) {
- route.push('#');
- route.push_str(info.name);
- route.push('-');
- route.push_str(next);
- } else {
- return None;
- }
- }
- }
- } else {
- route.push_str(rest);
- }
+ crate::link::resolve(link)
+ }
- if !route.contains('#') && !route.ends_with('/') {
- route.push('/');
+ fn nesting(&self) -> usize {
+ match self.nesting {
+ Some(nesting) => nesting,
+ None => panic!("headings are not allowed here:\n{}", self.text),
}
-
- Some(route)
}
}
@@ -466,15 +415,10 @@ fn html_attr_range(html: &str, attr: &str) -> Option<Range<usize>> {
}
/// Increase the nesting level of a Markdown heading.
-fn nest_heading(level: &mut md::HeadingLevel) {
- *level = match &level {
- md::HeadingLevel::H1 => md::HeadingLevel::H2,
- md::HeadingLevel::H2 => md::HeadingLevel::H3,
- md::HeadingLevel::H3 => md::HeadingLevel::H4,
- md::HeadingLevel::H4 => md::HeadingLevel::H5,
- md::HeadingLevel::H5 => md::HeadingLevel::H6,
- v => **v,
- };
+fn nest_heading(level: &mut md::HeadingLevel, nesting: usize) {
+ *level = ((*level as usize) + nesting)
+ .try_into()
+ .unwrap_or(md::HeadingLevel::H6);
}
/// A world for example compilations.
@@ -499,7 +443,7 @@ impl World for DocWorld {
fn file(&self, id: FileId) -> FileResult<Bytes> {
assert!(id.package().is_none());
- Ok(FILES
+ Ok(FILE_DIR
.get_file(id.vpath().as_rootless_path())
.unwrap_or_else(|| panic!("failed to load {:?}", id.vpath()))
.contents()
diff --git a/crates/typst-docs/src/lib.rs b/crates/typst-docs/src/lib.rs
index 96ae460c..3018c244 100644
--- a/crates/typst-docs/src/lib.rs
+++ b/crates/typst-docs/src/lib.rs
@@ -2,49 +2,39 @@
mod contribs;
mod html;
+mod link;
+mod model;
pub use contribs::{contributors, Author, Commit};
pub use html::Html;
+pub use model::*;
-use std::fmt::{self, Debug, Formatter};
use std::path::Path;
use comemo::Prehashed;
+use ecow::{eco_format, EcoString};
use heck::ToTitleCase;
use include_dir::{include_dir, Dir};
use once_cell::sync::Lazy;
use serde::de::DeserializeOwned;
-use serde::{Deserialize, Serialize};
+use serde::Deserialize;
use serde_yaml as yaml;
+use typst::diag::{bail, StrResult};
use typst::doc::Frame;
-use typst::eval::{CastInfo, Func, FuncInfo, Library, Module, ParamInfo, Value};
+use typst::eval::{CastInfo, Func, Library, Module, ParamInfo, Scope, Type, Value};
use typst::font::{Font, FontBook};
use typst::geom::{Abs, Smart};
use typst_library::layout::{Margin, PageElem};
-use unscanny::Scanner;
-static DOCS: Dir<'_> = include_dir!("$CARGO_MANIFEST_DIR/../../docs");
-static FILES: Dir<'_> = include_dir!("$CARGO_MANIFEST_DIR/../../assets/files");
-static DETAILS: Lazy<yaml::Mapping> = Lazy::new(|| yaml("reference/details.yml"));
-static GROUPS: Lazy<Vec<GroupData>> = Lazy::new(|| yaml("reference/groups.yml"));
+static DOCS_DIR: Dir<'_> = include_dir!("$CARGO_MANIFEST_DIR/../../docs");
+static FILE_DIR: Dir<'_> = include_dir!("$CARGO_MANIFEST_DIR/../../assets/files");
+static FONT_DIR: Dir<'_> = include_dir!("$CARGO_MANIFEST_DIR/../../assets/fonts");
-static FONTS: Lazy<(Prehashed<FontBook>, Vec<Font>)> = Lazy::new(|| {
- static DIR: Dir<'_> = include_dir!("$CARGO_MANIFEST_DIR/../../assets/fonts");
- let fonts: Vec<_> = DIR
- .files()
- .flat_map(|file| Font::iter(file.contents().into()))
- .collect();
- let book = FontBook::from_fonts(&fonts);
- (Prehashed::new(book), fonts)
-});
+static CATEGORIES: Lazy<yaml::Mapping> = Lazy::new(|| yaml("reference/categories.yml"));
+static GROUPS: Lazy<Vec<GroupData>> = Lazy::new(|| yaml("reference/groups.yml"));
static LIBRARY: Lazy<Prehashed<Library>> = Lazy::new(|| {
let mut lib = typst_library::build();
- // Hack for documenting the `mix` function in the color module.
- // Will be superseded by proper associated functions.
- lib.global
- .scope_mut()
- .define("mix", typst_library::compute::mix_func());
lib.styles
.set(PageElem::set_width(Smart::Custom(Abs::pt(240.0).into())));
lib.styles.set(PageElem::set_height(Smart::Auto));
@@ -55,13 +45,22 @@ static LIBRARY: Lazy<Prehashed<Library>> = Lazy::new(|| {
Prehashed::new(lib)
});
+static FONTS: Lazy<(Prehashed<FontBook>, Vec<Font>)> = Lazy::new(|| {
+ let fonts: Vec<_> = FONT_DIR
+ .files()
+ .flat_map(|file| Font::iter(file.contents().into()))
+ .collect();
+ let book = FontBook::from_fonts(&fonts);
+ (Prehashed::new(book), fonts)
+});
+
/// Build documentation pages.
pub fn provide(resolver: &dyn Resolver) -> Vec<PageModel> {
vec![
markdown_page(resolver, "/docs/", "overview.md").with_route("/docs/"),
tutorial_pages(resolver),
reference_pages(resolver),
- guides_pages(resolver),
+ guide_pages(resolver),
packages_page(resolver),
markdown_page(resolver, "/docs/", "changelog.md"),
markdown_page(resolver, "/docs/", "roadmap.md"),
@@ -84,54 +83,32 @@ pub trait Resolver {
fn commits(&self, from: &str, to: &str) -> Vec<Commit>;
}
-/// Details about a documentation page and its children.
-#[derive(Debug, Serialize)]
-pub struct PageModel {
- pub route: String,
- pub title: String,
- pub description: String,
- pub part: Option<&'static str>,
- pub outline: Vec<OutlineItem>,
- pub body: BodyModel,
- pub children: Vec<Self>,
-}
-
-impl PageModel {
- fn with_route(self, route: &str) -> Self {
- Self { route: route.into(), ..self }
- }
-
- fn with_part(self, part: &'static str) -> Self {
- Self { part: Some(part), ..self }
+/// Create a page from a markdown file.
+#[track_caller]
+fn markdown_page(
+ resolver: &dyn Resolver,
+ parent: &str,
+ path: impl AsRef<Path>,
+) -> PageModel {
+ assert!(parent.starts_with('/') && parent.ends_with('/'));
+ let md = DOCS_DIR.get_file(path).unwrap().contents_utf8().unwrap();
+ let html = Html::markdown(resolver, md, Some(0));
+ let title: EcoString = html.title().expect("chapter lacks a title").into();
+ PageModel {
+ route: eco_format!("{parent}{}/", urlify(&title)),
+ title,
+ description: html.description().unwrap(),
+ part: None,
+ outline: html.outline(),
+ body: BodyModel::Html(html),
+ children: vec![],
}
}
-/// An element in the "On This Page" outline.
-#[derive(Debug, Clone, Serialize)]
-pub struct OutlineItem {
- id: String,
- name: String,
- children: Vec<Self>,
-}
-
-/// Details about the body of a documentation page.
-#[derive(Debug, Serialize)]
-#[serde(rename_all = "camelCase")]
-#[serde(tag = "kind", content = "content")]
-pub enum BodyModel {
- Html(Html),
- Category(CategoryModel),
- Func(FuncModel),
- Funcs(FuncsModel),
- Type(TypeModel),
- Symbols(SymbolsModel),
- Packages(Html),
-}
-
/// Build the tutorial.
fn tutorial_pages(resolver: &dyn Resolver) -> PageModel {
let mut page = markdown_page(resolver, "/docs/", "tutorial/welcome.md");
- page.children = DOCS
+ page.children = DOCS_DIR
.get_dir("tutorial")
.unwrap()
.files()
@@ -149,23 +126,20 @@ fn reference_pages(resolver: &dyn Resolver) -> PageModel {
.with_part("Language"),
markdown_page(resolver, "/docs/reference/", "reference/styling.md"),
markdown_page(resolver, "/docs/reference/", "reference/scripting.md"),
- types_page(resolver, "/docs/reference/"),
- category_page(resolver, "text").with_part("Content"),
+ category_page(resolver, "foundations").with_part("Library"),
+ category_page(resolver, "text"),
category_page(resolver, "math"),
category_page(resolver, "layout"),
category_page(resolver, "visualize"),
category_page(resolver, "meta"),
category_page(resolver, "symbols"),
- category_page(resolver, "foundations").with_part("Compute"),
- category_page(resolver, "calculate"),
- category_page(resolver, "construct"),
category_page(resolver, "data-loading"),
];
page
}
/// Build the guides section.
-fn guides_pages(resolver: &dyn Resolver) -> PageModel {
+fn guide_pages(resolver: &dyn Resolver) -> PageModel {
let mut page = markdown_page(resolver, "/docs/", "guides/welcome.md");
page.children = vec![
markdown_page(resolver, "/docs/guides/", "guides/guide-for-latex-users.md"),
@@ -182,257 +156,162 @@ fn packages_page(resolver: &dyn Resolver) -> PageModel {
description: "Packages for Typst.".into(),
part: None,
outline: vec![],
- body: BodyModel::Packages(Html::markdown(resolver, details("packages"))),
- children: vec![],
- }
-}
-
-/// Create a page from a markdown file.
-#[track_caller]
-fn markdown_page(
- resolver: &dyn Resolver,
- parent: &str,
- path: impl AsRef<Path>,
-) -> PageModel {
- assert!(parent.starts_with('/') && parent.ends_with('/'));
- let md = DOCS.get_file(path).unwrap().contents_utf8().unwrap();
- let html = Html::markdown(resolver, md);
- let title = html.title().expect("chapter lacks a title").to_string();
- PageModel {
- route: format!("{parent}{}/", urlify(&title)),
- title,
- description: html.description().unwrap(),
- part: None,
- outline: html.outline(),
- body: BodyModel::Html(html),
+ body: BodyModel::Packages(Html::markdown(
+ resolver,
+ category_details("packages"),
+ Some(1),
+ )),
children: vec![],
}
}
-/// Details about a category.
-#[derive(Debug, Serialize)]
-pub struct CategoryModel {
- pub name: String,
- pub details: Html,
- pub kind: &'static str,
- pub items: Vec<CategoryItem>,
- pub markup_shorthands: Option<Vec<SymbolModel>>,
- pub math_shorthands: Option<Vec<SymbolModel>>,
-}
-
-/// Details about a category item.
-#[derive(Debug, Serialize)]
-pub struct CategoryItem {
- pub name: String,
- pub route: String,
- pub oneliner: String,
- pub code: bool,
-}
-
/// Create a page for a category.
#[track_caller]
fn category_page(resolver: &dyn Resolver, category: &str) -> PageModel {
- let route = format!("/docs/reference/{category}/");
+ let route = eco_format!("/docs/reference/{category}/");
let mut children = vec![];
let mut items = vec![];
- let focus = match category {
- "math" => &LIBRARY.math,
- "calculate" => module(&LIBRARY.global, "calc").unwrap(),
- _ => &LIBRARY.global,
- };
-
- let parents: &[&str] = match category {
- "math" => &[],
- "calculate" => &["calc"],
- _ => &[],
+ let (module, path): (&Module, &[&str]) = match category {
+ "math" => (&LIBRARY.math, &["math"]),
+ _ => (&LIBRARY.global, &[]),
};
- let grouped = match category {
- "math" => GROUPS.as_slice(),
- _ => &[],
- };
-
- // Add functions.
- for (_, value) in focus.scope().iter() {
- let Value::Func(func) = value else { continue };
- let Some(info) = func.info() else { continue };
- if info.category != category {
- continue;
+ // Add groups.
+ for mut group in GROUPS.iter().filter(|g| g.category == category).cloned() {
+ let mut focus = module;
+ if group.name == "calc" {
+ focus = get_module(focus, "calc").unwrap();
+ group.functions = focus
+ .scope()
+ .iter()
+ .filter(|(_, v)| matches!(v, Value::Func(_)))
+ .map(|(k, _)| k.clone())
+ .collect();
}
+ let (child, item) = group_page(resolver, &route, &group, focus.scope());
+ children.push(child);
+ items.push(item);
+ }
- // Skip grouped functions.
- if grouped
- .iter()
- .flat_map(|group| &group.functions)
- .any(|f| f == info.name)
- {
+ // Add functions.
+ let scope = module.scope();
+ for (name, value) in scope.iter() {
+ if scope.get_category(name) != Some(category) {
continue;
}
- let subpage = function_page(resolver, &route, func, info, parents);
- items.push(CategoryItem {
- name: info.name.into(),
- route: subpage.route.clone(),
- oneliner: oneliner(info.docs).into(),
- code: true,
- });
- children.push(subpage);
- }
+ if category == "math" {
+ // Skip grouped functions.
+ if GROUPS.iter().flat_map(|group| &group.functions).any(|f| f == name) {
+ continue;
+ }
- // Add grouped functions.
- for group in grouped {
- let mut functions = vec![];
- let mut outline = vec![OutlineItem {
- id: "summary".into(),
- name: "Summary".into(),
- children: vec![],
- }];
-
- for name in &group.functions {
- let value = focus.get(name).unwrap();
- let Value::Func(func) = value else { panic!("not a function") };
- let info = func.info().unwrap();
- let func = func_model(resolver, func, info, &[], info.name);
- let id = urlify(&func.path.join("-"));
- let children = func_outline(&func, &id, false);
- outline.push(OutlineItem { id, name: func.display.into(), children });
- functions.push(func);
+ // Already documented in the text category.
+ if name == "text" {
+ continue;
+ }
}
- let route = format!("{}{}/", route, group.name);
- items.push(CategoryItem {
- name: group.name.clone(),
- route: route.clone(),
- oneliner: oneliner(&group.description).into(),
- code: false,
- });
-
- children.push(PageModel {
- route,
- title: group.display.clone(),
- description: format!("Documentation for {} group of functions.", group.name),
- part: None,
- outline,
- body: BodyModel::Funcs(FuncsModel {
- name: group.name.clone(),
- display: group.display.clone(),
- details: Html::markdown(resolver, &group.description),
- functions,
- }),
- children: vec![],
- });
+ match value {
+ Value::Func(func) => {
+ let name = func.name().unwrap();
+
+ let subpage = func_page(resolver, &route, func, path);
+ items.push(CategoryItem {
+ name: name.into(),
+ route: subpage.route.clone(),
+ oneliner: oneliner(func.docs().unwrap_or_default()).into(),
+ code: true,
+ });
+ children.push(subpage);
+ }
+ Value::Type(ty) => {
+ let subpage = type_page(resolver, &route, ty);
+ items.push(CategoryItem {
+ name: ty.short_name().into(),
+ route: subpage.route.clone(),
+ oneliner: oneliner(ty.docs()).into(),
+ code: true,
+ });
+ children.push(subpage);
+ }
+ _ => {}
+ }
}
children.sort_by_cached_key(|child| child.title.clone());
items.sort_by_cached_key(|item| item.name.clone());
// Add symbol pages. These are ordered manually.
- let mut markup_shorthands = vec![];
- let mut math_shorthands = vec![];
+ let mut shorthands = None;
if category == "symbols" {
+ let mut markup = vec![];
+ let mut math = vec![];
for module in ["sym", "emoji"] {
- let subpage = symbol_page(resolver, &route, module);
+ let subpage = symbols_page(resolver, &route, module);
let BodyModel::Symbols(model) = &subpage.body else { continue };
let list = &model.list;
- markup_shorthands.extend(
+ markup.extend(
list.iter()
.filter(|symbol| symbol.markup_shorthand.is_some())
.cloned(),
);
- math_shorthands.extend(
+ math.extend(
list.iter().filter(|symbol| symbol.math_shorthand.is_some()).cloned(),
);
items.push(CategoryItem {
name: module.into(),
route: subpage.route.clone(),
- oneliner: oneliner(details(module)).into(),
+ oneliner: oneliner(category_details(module)).into(),
code: true,
});
children.push(subpage);
}
+ shorthands = Some(ShorthandsModel { markup, math });
}
- let name = category.to_title_case();
- let kind = match category {
- "symbols" => "Modules",
- _ => "Functions",
- };
+ let name: EcoString = category.to_title_case().into();
PageModel {
route,
title: name.clone(),
- description: format!("Documentation for functions related to {name} in Typst."),
+ description: eco_format!(
+ "Documentation for functions related to {name} in Typst."
+ ),
part: None,
- outline: category_outline(kind),
+ outline: category_outline(),
body: BodyModel::Category(CategoryModel {
name,
- details: Html::markdown(resolver, details(category)),
- kind,
+ details: Html::markdown(resolver, category_details(category), Some(1)),
items,
- markup_shorthands: Some(markup_shorthands),
- math_shorthands: Some(math_shorthands),
+ shorthands,
}),
children,
}
}
/// Produce an outline for a category page.
-fn category_outline(kind: &str) -> Vec<OutlineItem> {
- vec![
- OutlineItem {
- id: "summary".into(),
- name: "Summary".into(),
- children: vec![],
- },
- OutlineItem {
- id: urlify(kind),
- name: kind.into(),
- children: vec![],
- },
- ]
-}
-
-/// Details about a function.
-#[derive(Debug, Serialize)]
-pub struct FuncModel {
- pub path: Vec<&'static str>,
- pub display: &'static str,
- pub keywords: Option<&'static str>,
- pub oneliner: &'static str,
- pub element: bool,
- pub details: Html,
- pub params: Vec<ParamModel>,
- pub returns: Vec<&'static str>,
- pub methods: Vec<MethodModel>,
- pub scope: Vec<Self>,
-}
-
-/// Details about a group of functions.
-#[derive(Debug, Serialize)]
-pub struct FuncsModel {
- pub name: String,
- pub display: String,
- pub details: Html,
- pub functions: Vec<FuncModel>,
+fn category_outline() -> Vec<OutlineItem> {
+ vec![OutlineItem::from_name("Summary"), OutlineItem::from_name("Definitions")]
}
/// Create a page for a function.
-fn function_page(
+fn func_page(
resolver: &dyn Resolver,
parent: &str,
func: &Func,
- info: &FuncInfo,
- parents: &[&'static str],
+ path: &[&str],
) -> PageModel {
- let model = func_model(resolver, func, info, parents, "");
+ let model = func_model(resolver, func, path, false);
+ let name = func.name().unwrap();
PageModel {
- route: format!("{parent}{}/", urlify(info.name)),
- title: info.display.to_string(),
- description: format!("Documentation for the `{}` function.", info.name),
+ route: eco_format!("{parent}{}/", urlify(name)),
+ title: func.title().unwrap().into(),
+ description: eco_format!("Documentation for the `{name}` function."),
part: None,
- outline: func_outline(&model, "", true),
+ outline: func_outline(&model, ""),
body: BodyModel::Func(model),
children: vec![],
}
@@ -442,143 +321,63 @@ fn function_page(
fn func_model(
resolver: &dyn Resolver,
func: &Func,
- info: &FuncInfo,
- parents: &[&'static str],
- id_base: &str,
+ path: &[&str],
+ nested: bool,
) -> FuncModel {
- let mut s = unscanny::Scanner::new(info.docs);
- let docs = s.eat_until("\n## Methods").trim();
-
- let mut path = parents.to_vec();
- let mut name = info.name;
- for parent in parents.iter().rev() {
- name = name
- .strip_prefix(parent)
- .or(name.strip_prefix(parent.strip_suffix('s').unwrap_or(parent)))
- .unwrap_or(name)
- .trim_matches('-');
- }
- path.push(name);
+ let name = func.name().unwrap();
+ let scope = func.scope().unwrap();
+ let docs = func.docs().unwrap();
- let scope = info
- .scope
- .iter()
- .filter_map(|(_, value)| {
- let Value::Func(func) = value else { return None };
- let info = func.info().unwrap();
- Some(func_model(resolver, func, info, &path, id_base))
- })
- .collect();
+ let mut self_ = false;
+ let mut params = func.params().unwrap();
+ if params.first().map_or(false, |first| first.name == "self") {
+ self_ = true;
+ params = &params[1..];
+ }
let mut returns = vec![];
- casts(resolver, &mut returns, &mut vec![], &info.returns);
+ casts(resolver, &mut returns, &mut vec![], func.returns().unwrap());
returns.sort_by_key(|ty| type_index(ty));
if returns == ["none"] {
returns.clear();
}
+ let nesting = if nested { None } else { Some(1) };
+ let (details, example) =
+ if nested { split_details_and_example(docs) } else { (docs, None) };
+
FuncModel {
- path,
- display: info.display,
- keywords: info.keywords,
- oneliner: oneliner(docs),
+ path: path.iter().copied().map(Into::into).collect(),
+ name: name.into(),
+ title: func.title().unwrap(),
+ keywords: func.keywords(),
+ oneliner: oneliner(details),
element: func.element().is_some(),
- details: Html::markdown_with_id_base(resolver, docs, id_base),
- params: info.params.iter().map(|param| param_model(resolver, param)).collect(),
+ details: Html::markdown(resolver, details, nesting),
+ example: example.map(|md| Html::markdown(resolver, md, None)),
+ self_,
+ params: params.iter().map(|param| param_model(resolver, param)).collect(),
returns,
- methods: method_models(resolver, info.docs),
- scope,
- }
-}
-
-/// Produce an outline for a function page.
-fn func_outline(model: &FuncModel, base: &str, summary: bool) -> Vec<OutlineItem> {
- let mut outline = vec![];
-
- if summary {
- outline.push(OutlineItem {
- id: "summary".into(),
- name: "Summary".into(),
- children: vec![],
- });
+ scope: scope_models(resolver, name, scope),
}
-
- outline.extend(model.details.outline());
-
- if !model.params.is_empty() {
- let join = if base.is_empty() { "" } else { "-" };
- outline.push(OutlineItem {
- id: format!("{base}{join}parameters"),
- name: "Parameters".into(),
- children: model
- .params
- .iter()
- .map(|param| OutlineItem {
- id: format!("{base}{join}parameters-{}", urlify(param.name)),
- name: param.name.into(),
- children: vec![],
- })
- .collect(),
- });
- }
-
- for func in &model.scope {
- let id = urlify(&func.path.join("-"));
- let children = func_outline(func, &id, false);
- outline.push(OutlineItem { id, name: func.display.into(), children })
- }
-
- outline.extend(methods_outline(&model.methods));
- outline
-}
-
-/// Details about a function parameter.
-#[derive(Debug, Serialize)]
-pub struct ParamModel {
- pub name: &'static str,
- pub details: Html,
- pub example: Option<Html>,
- pub types: Vec<&'static str>,
- pub strings: Vec<StrParam>,
- pub default: Option<Html>,
- pub positional: bool,
- pub named: bool,
- pub required: bool,
- pub variadic: bool,
- pub settable: bool,
-}
-
-/// A specific string that can be passed as an argument.
-#[derive(Debug, Serialize)]
-pub struct StrParam {
- pub string: String,
- pub details: Html,
}
/// Produce a parameter's model.
fn param_model(resolver: &dyn Resolver, info: &ParamInfo) -> ParamModel {
+ let (details, example) = split_details_and_example(info.docs);
+
let mut types = vec![];
let mut strings = vec![];
- casts(resolver, &mut types, &mut strings, &info.cast);
+ casts(resolver, &mut types, &mut strings, &info.input);
if !strings.is_empty() && !types.contains(&"string") {
types.push("string");
}
types.sort_by_key(|ty| type_index(ty));
- let mut details = info.docs;
- let mut example = None;
- if let Some(mut i) = info.docs.find("```example") {
- while info.docs[..i].ends_with('`') {
- i -= 1;
- }
- details = &info.docs[..i];
- example = Some(&info.docs[i..]);
- }
-
ParamModel {
name: info.name,
- details: Html::markdown(resolver, details),
- example: example.map(|md| Html::markdown(resolver, md)),
+ details: Html::markdown(resolver, details, None),
+ example: example.map(|md| Html::markdown(resolver, md, None)),
types,
strings,
default: info.default.map(|default| {
@@ -593,6 +392,20 @@ fn param_model(resolver: &dyn Resolver, info: &ParamInfo) -> ParamModel {
}
}
+/// Split up documentation into details and an example.
+fn split_details_and_example(docs: &str) -> (&str, Option<&str>) {
+ let mut details = docs;
+ let mut example = None;
+ if let Some(mut i) = docs.find("```") {
+ while docs[..i].ends_with('`') {
+ i -= 1;
+ }
+ details = &docs[..i];
+ example = Some(&docs[i..]);
+ }
+ (details, example)
+}
+
/// Process cast information into types and strings.
fn casts(
resolver: &dyn Resolver,
@@ -603,11 +416,11 @@ fn casts(
match info {
CastInfo::Any => types.push("any"),
CastInfo::Value(Value::Str(string), docs) => strings.push(StrParam {
- string: string.to_string(),
- details: Html::markdown(resolver, docs),
+ string: string.clone().into(),
+ details: Html::markdown(resolver, docs, None),
}),
CastInfo::Value(..) => {}
- CastInfo::Type(ty) => types.push(ty),
+ CastInfo::Type(ty) => types.push(ty.short_name()),
CastInfo::Union(options) => {
for option in options {
casts(resolver, types, strings, option);
@@ -616,258 +429,216 @@ fn casts(
}
}
-/// A collection of symbols.
-#[derive(Debug, Serialize)]
-pub struct TypeModel {
- pub name: String,
- pub oneliner: &'static str,
- pub details: Html,
- pub methods: Vec<MethodModel>,
+/// Produce models for a function's scope.
+fn scope_models(resolver: &dyn Resolver, name: &str, scope: &Scope) -> Vec<FuncModel> {
+ scope
+ .iter()
+ .filter_map(|(_, value)| {
+ let Value::Func(func) = value else { return None };
+ Some(func_model(resolver, func, &[name], true))
+ })
+ .collect()
}
-/// Details about a built-in method on a type.
-#[derive(Debug, Serialize)]
-pub struct MethodModel {
- pub name: &'static str,
- pub details: Html,
- pub params: Vec<ParamModel>,
- pub returns: Vec<&'static str>,
-}
+/// Produce an outline for a function page.
+fn func_outline(model: &FuncModel, id_base: &str) -> Vec<OutlineItem> {
+ let mut outline = vec![];
-/// Create a page for the types.
-fn types_page(resolver: &dyn Resolver, parent: &str) -> PageModel {
- let route = format!("{parent}types/");
- let mut children = vec![];
- let mut items = vec![];
+ if id_base.is_empty() {
+ outline.push(OutlineItem::from_name("Summary"));
+ outline.extend(model.details.outline());
+
+ if !model.params.is_empty() {
+ outline.push(OutlineItem {
+ id: "parameters".into(),
+ name: "Parameters".into(),
+ children: model
+ .params
+ .iter()
+ .map(|param| OutlineItem {
+ id: eco_format!("parameters-{}", urlify(param.name)),
+ name: param.name.into(),
+ children: vec![],
+ })
+ .collect(),
+ });
+ }
- for model in type_models(resolver) {
- let route = format!("{route}{}/", urlify(&model.name));
- items.push(CategoryItem {
- name: model.name.clone(),
- route: route.clone(),
- oneliner: model.oneliner.into(),
- code: true,
- });
- children.push(PageModel {
- route,
- title: model.name.to_title_case(),
- description: format!("Documentation for the `{}` type.", model.name),
- part: None,
- outline: type_outline(&model),
- body: BodyModel::Type(model),
+ outline.extend(scope_outline(&model.scope));
+ } else {
+ outline.extend(model.params.iter().map(|param| OutlineItem {
+ id: eco_format!("{id_base}-{}", urlify(param.name)),
+ name: param.name.into(),
children: vec![],
- });
+ }));
}
- PageModel {
- route,
- title: "Types".into(),
- description: "Documentation for Typst's built-in types.".into(),
- part: None,
- outline: category_outline("Types"),
- body: BodyModel::Category(CategoryModel {
- name: "Types".into(),
- details: Html::markdown(resolver, details("types")),
- kind: "Types",
- items,
- markup_shorthands: None,
- math_shorthands: None,
- }),
- children,
- }
+ outline
}
-/// Produce the types' models.
-fn type_models(resolver: &dyn Resolver) -> Vec<TypeModel> {
- let file = DOCS.get_file("reference/types.md").unwrap();
- let text = file.contents_utf8().unwrap();
-
- let mut s = unscanny::Scanner::new(text);
- let mut types = vec![];
-
- while s.eat_if("# ") {
- let part = s.eat_until("\n# ");
- types.push(type_model(resolver, part));
- s.eat_if('\n');
+/// Produce an outline for a function scope.
+fn scope_outline(scope: &[FuncModel]) -> Option<OutlineItem> {
+ if scope.is_empty() {
+ return None;
}
- types
-}
-
-/// Produce a type's model.
-fn type_model(resolver: &dyn Resolver, part: &'static str) -> TypeModel {
- let mut s = unscanny::Scanner::new(part);
- let display = s.eat_until('\n').trim();
- let docs = s.eat_until("\n## Methods").trim();
- TypeModel {
- name: display.to_lowercase(),
- oneliner: oneliner(docs),
- details: Html::markdown(resolver, docs),
- methods: method_models(resolver, part),
- }
+ Some(OutlineItem {
+ id: "definitions".into(),
+ name: "Definitions".into(),
+ children: scope
+ .iter()
+ .map(|func| {
+ let id = urlify(&eco_format!("definitions-{}", func.name));
+ let children = func_outline(func, &id);
+ OutlineItem { id, name: func.title.into(), children }
+ })
+ .collect(),
+ })
}
-/// Produce multiple methods' models.
-fn method_models(resolver: &dyn Resolver, docs: &'static str) -> Vec<MethodModel> {
- let mut s = unscanny::Scanner::new(docs);
- s.eat_until("\n## Methods");
- s.eat_whitespace();
-
- let mut methods = vec![];
- if s.eat_if("## Methods") {
- s.eat_until("\n### ");
- while s.eat_if("\n### ") {
- methods.push(method_model(resolver, s.eat_until("\n### ")));
- }
+/// Create a page for a group of functions.
+fn group_page(
+ resolver: &dyn Resolver,
+ parent: &str,
+ group: &GroupData,
+ scope: &Scope,
+) -> (PageModel, CategoryItem) {
+ let mut functions = vec![];
+ let mut outline = vec![OutlineItem::from_name("Summary")];
+
+ let path: Vec<_> = group.path.iter().map(|s| s.as_str()).collect();
+ let details = Html::markdown(resolver, &group.description, Some(1));
+ outline.extend(details.outline());
+
+ let mut outline_items = vec![];
+ for name in &group.functions {
+ let value = scope.get(name).unwrap();
+ let Value::Func(func) = value else { panic!("not a function") };
+ let func = func_model(resolver, func, &path, true);
+ let id_base = urlify(&eco_format!("functions-{}", func.name));
+ let children = func_outline(&func, &id_base);
+ outline_items.push(OutlineItem {
+ id: id_base,
+ name: func.title.into(),
+ children,
+ });
+ functions.push(func);
}
- methods
-}
-
-/// Produce a method's model.
-fn method_model(resolver: &dyn Resolver, part: &'static str) -> MethodModel {
- let mut s = unscanny::Scanner::new(part);
- let mut params = vec![];
- let mut returns = vec![];
-
- let name = s.eat_until('(').trim();
- s.expect("()");
- let docs = s.eat_until("\n- ").trim();
-
- while s.eat_if("\n- ") {
- let name = s.eat_until(':');
- s.expect(": ");
- let types: Vec<_> =
- s.eat_until(['(', '\n']).split(" or ").map(str::trim).collect();
- if !types.iter().all(|ty| type_index(ty) != usize::MAX) {
- panic!(
- "unknown type in method {} parameter {}",
- name,
- types.iter().find(|ty| type_index(ty) == usize::MAX).unwrap()
- )
- }
+ outline.push(OutlineItem {
+ id: "functions".into(),
+ name: "Functions".into(),
+ children: outline_items,
+ });
- if name == "returns" {
- returns = types;
- continue;
- }
+ let model = PageModel {
+ route: eco_format!("{parent}{}", group.name),
+ title: group.display.clone(),
+ description: eco_format!("Documentation for the {} functions.", group.name),
+ part: None,
+ outline,
+ body: BodyModel::Group(GroupModel {
+ name: group.name.clone(),
+ title: group.display.clone(),
+ details,
+ functions,
+ }),
+ children: vec![],
+ };
- s.expect('(');
-
- let mut named = false;
- let mut positional = false;
- let mut required = false;
- let mut variadic = false;
- for part in s.eat_until(')').split(',').map(str::trim) {
- match part {
- "named" => named = true,
- "positional" => positional = true,
- "required" => required = true,
- "variadic" => variadic = true,
- _ => panic!("unknown parameter flag {:?}", part),
- }
- }
+ let item = CategoryItem {
+ name: group.name.clone(),
+ route: model.route.clone(),
+ oneliner: oneliner(&group.description).into(),
+ code: false,
+ };
- s.expect(')');
+ (model, item)
+}
- params.push(ParamModel {
- name,
- details: Html::markdown(resolver, s.eat_until("\n- ").trim()),
- example: None,
- types,
- strings: vec![],
- default: None,
- positional,
- named,
- required,
- variadic,
- settable: false,
- });
+/// Create a page for a type.
+fn type_page(resolver: &dyn Resolver, parent: &str, ty: &Type) -> PageModel {
+ let model = type_model(resolver, ty);
+ PageModel {
+ route: eco_format!("{parent}{}/", urlify(ty.short_name())),
+ title: ty.title().into(),
+ description: eco_format!("Documentation for the {} type.", ty.title()),
+ part: None,
+ outline: type_outline(&model),
+ body: BodyModel::Type(model),
+ children: vec![],
}
+}
- MethodModel {
- name,
- details: Html::markdown(resolver, docs),
- params,
- returns,
+/// Produce a type's model.
+fn type_model(resolver: &dyn Resolver, ty: &Type) -> TypeModel {
+ TypeModel {
+ name: ty.short_name(),
+ title: ty.title(),
+ keywords: ty.keywords(),
+ oneliner: oneliner(ty.docs()),
+ details: Html::markdown(resolver, ty.docs(), Some(1)),
+ constructor: ty
+ .constructor()
+ .ok()
+ .map(|func| func_model(resolver, &func, &[], true)),
+ scope: scope_models(resolver, ty.short_name(), ty.scope()),
}
}
/// Produce an outline for a type page.
fn type_outline(model: &TypeModel) -> Vec<OutlineItem> {
- let mut outline = vec![OutlineItem {
- id: "summary".into(),
- name: "Summary".into(),
- children: vec![],
- }];
+ let mut outline = vec![OutlineItem::from_name("Summary")];
+ outline.extend(model.details.outline());
+
+ if let Some(func) = &model.constructor {
+ outline.push(OutlineItem {
+ id: "constructor".into(),
+ name: "Constructor".into(),
+ children: func_outline(func, "constructor"),
+ });
+ }
- outline.extend(methods_outline(&model.methods));
+ outline.extend(scope_outline(&model.scope));
outline
}
-/// Produce an outline for a type's method.
-fn methods_outline(methods: &[MethodModel]) -> Option<OutlineItem> {
- (!methods.is_empty()).then(|| OutlineItem {
- id: "methods".into(),
- name: "Methods".into(),
- children: methods.iter().map(method_outline).collect(),
- })
-}
+/// Create a page for symbols.
+fn symbols_page(resolver: &dyn Resolver, parent: &str, name: &str) -> PageModel {
+ let module = get_module(&LIBRARY.global, name).unwrap();
+ let title = match name {
+ "sym" => "General",
+ "emoji" => "Emoji",
+ _ => unreachable!(),
+ };
-/// Produce an outline for a type's method.
-fn method_outline(model: &MethodModel) -> OutlineItem {
- OutlineItem {
- id: format!("methods-{}", urlify(model.name)),
- name: model.name.into(),
- children: model
- .params
- .iter()
- .map(|param| OutlineItem {
- id: format!(
- "methods-{}-parameters-{}",
- urlify(model.name),
- urlify(param.name)
- ),
- name: param.name.into(),
- children: vec![],
- })
- .collect(),
+ let model = symbols_model(resolver, name, title, module.scope());
+ PageModel {
+ route: eco_format!("{parent}{name}/"),
+ title: title.into(),
+ description: eco_format!("Documentation for the `{name}` module."),
+ part: None,
+ outline: vec![],
+ body: BodyModel::Symbols(model),
+ children: vec![],
}
}
-/// A collection of symbols.
-#[derive(Debug, Serialize)]
-pub struct SymbolsModel {
- pub name: &'static str,
- pub details: Html,
- pub list: Vec<SymbolModel>,
-}
-
-/// Details about a symbol.
-#[derive(Debug, Clone, Serialize)]
-#[serde(rename_all = "camelCase")]
-pub struct SymbolModel {
- pub name: String,
- pub markup_shorthand: Option<&'static str>,
- pub math_shorthand: Option<&'static str>,
- pub codepoint: u32,
- pub accent: bool,
- pub unicode_name: Option<String>,
- pub alternates: Vec<String>,
-}
-
-/// Create a page for symbols.
-fn symbol_page(resolver: &dyn Resolver, parent: &str, name: &str) -> PageModel {
- let module = module(&LIBRARY.global, name).unwrap();
-
+/// Produce a symbol list's model.
+fn symbols_model(
+ resolver: &dyn Resolver,
+ name: &str,
+ title: &'static str,
+ scope: &Scope,
+) -> SymbolsModel {
let mut list = vec![];
- for (name, value) in module.scope().iter() {
+ for (name, value) in scope.iter() {
let Value::Symbol(symbol) = value else { continue };
let complete = |variant: &str| {
if variant.is_empty() {
- name.into()
+ name.clone()
} else {
- format!("{}.{}", name, variant)
+ eco_format!("{}.{}", name, variant)
}
};
@@ -883,7 +654,7 @@ fn symbol_page(resolver: &dyn Resolver, parent: &str, name: &str) -> PageModel {
codepoint: c as u32,
accent: typst::eval::Symbol::combining_accent(c).is_some(),
unicode_name: unicode_names2::name(c)
- .map(|s| s.to_string().to_title_case()),
+ .map(|s| s.to_string().to_title_case().into()),
alternates: symbol
.variants()
.filter(|(other, _)| other != &variant)
@@ -893,63 +664,40 @@ fn symbol_page(resolver: &dyn Resolver, parent: &str, name: &str) -> PageModel {
}
}
- let title = match name {
- "sym" => "General",
- "emoji" => "Emoji",
- _ => unreachable!(),
- };
-
- PageModel {
- route: format!("{parent}{name}/"),
- title: title.into(),
- description: format!("Documentation for the `{name}` module."),
- part: None,
- outline: vec![],
- body: BodyModel::Symbols(SymbolsModel {
- name: title,
- details: Html::markdown(resolver, details(name)),
- list,
- }),
- children: vec![],
+ SymbolsModel {
+ name: title,
+ details: Html::markdown(resolver, category_details(name), Some(1)),
+ list,
}
}
-/// Data about a collection of functions.
-#[derive(Debug, Deserialize)]
-struct GroupData {
- name: String,
- display: String,
- functions: Vec<String>,
- description: String,
-}
-
/// Extract a module from another module.
#[track_caller]
-fn module<'a>(parent: &'a Module, name: &str) -> Result<&'a Module, String> {
+fn get_module<'a>(parent: &'a Module, name: &str) -> StrResult<&'a Module> {
match parent.scope().get(name) {
Some(Value::Module(module)) => Ok(module),
- _ => Err(format!("module doesn't contain module `{name}`")),
+ _ => bail!("module doesn't contain module `{name}`"),
}
}
/// Load YAML from a path.
#[track_caller]
fn yaml<T: DeserializeOwned>(path: &str) -> T {
- let file = DOCS.get_file(path).unwrap();
+ let file = DOCS_DIR.get_file(path).unwrap();
yaml::from_slice(file.contents()).unwrap()
}
/// Load details for an identifying key.
#[track_caller]
-fn details(key: &str) -> &str {
- DETAILS
+fn category_details(key: &str) -> &str {
+ CATEGORIES
.get(&yaml::Value::String(key.into()))
.and_then(|value| value.as_str())
.unwrap_or_else(|| panic!("missing details for {key}"))
}
/// Turn a title into an URL fragment.
-pub fn urlify(title: &str) -> String {
+pub fn urlify(title: &str) -> EcoString {
title
.chars()
.map(|c| c.to_ascii_lowercase())
@@ -974,33 +722,47 @@ const TYPE_ORDER: &[&str] = &[
"any",
"none",
"auto",
- "boolean",
- "integer",
+ "bool",
+ "int",
"float",
"length",
"angle",
"ratio",
- "relative length",
+ "relative",
"fraction",
"color",
"datetime",
- "string",
+ "duration",
+ "str",
"bytes",
"regex",
"label",
"content",
"array",
- "dictionary",
- "function",
- "arguments",
+ "dict",
+ "func",
+ "args",
+ "selector",
"location",
- "dir",
+ "direction",
"alignment",
- "2d alignment",
- "selector",
+ "alignment2d",
"stroke",
];
+/// Data about a collection of functions.
+#[derive(Debug, Clone, Deserialize)]
+struct GroupData {
+ name: EcoString,
+ category: EcoString,
+ display: EcoString,
+ #[serde(default)]
+ path: Vec<EcoString>,
+ #[serde(default)]
+ functions: Vec<EcoString>,
+ description: EcoString,
+}
+
#[cfg(test)]
mod tests {
use super::*;
diff --git a/crates/typst-docs/src/link.rs b/crates/typst-docs/src/link.rs
new file mode 100644
index 00000000..5d7a5485
--- /dev/null
+++ b/crates/typst-docs/src/link.rs
@@ -0,0 +1,102 @@
+use typst::diag::{bail, StrResult};
+use typst::eval::Func;
+
+use super::{get_module, GROUPS, LIBRARY};
+
+/// Resolve an intra-doc link.
+pub fn resolve(link: &str) -> StrResult<String> {
+ if link.starts_with('#') || link.starts_with("http") {
+ return Ok(link.to_string());
+ }
+
+ let (head, tail) = split_link(link)?;
+ let mut route = match resolve_known(head) {
+ Some(route) => route.into(),
+ None => resolve_definition(head)?,
+ };
+
+ if !tail.is_empty() {
+ route.push('/');
+ route.push_str(tail);
+ }
+
+ if !route.contains('#') && !route.ends_with('/') {
+ route.push('/');
+ }
+
+ Ok(route)
+}
+
+/// Split a link at the first slash.
+fn split_link(link: &str) -> StrResult<(&str, &str)> {
+ let first = link.split('/').next().unwrap_or(link);
+ let rest = link[first.len()..].trim_start_matches('/');
+ Ok((first, rest))
+}
+
+/// Resolve a `$` link head to a known destination.
+fn resolve_known(head: &str) -> Option<&'static str> {
+ Some(match head {
+ "$tutorial" => "/docs/tutorial/",
+ "$reference" => "/docs/reference/",
+ "$category" => "/docs/reference/",
+ "$syntax" => "/docs/reference/syntax/",
+ "$styling" => "/docs/reference/styling/",
+ "$scripting" => "/docs/reference/scripting/",
+ "$guides" => "/docs/guides/",
+ "$packages" => "/docs/packages/",
+ "$changelog" => "/docs/changelog/",
+ "$community" => "/docs/community/",
+ _ => return None,
+ })
+}
+
+/// Resolve a `$` link to a global definition.
+fn resolve_definition(head: &str) -> StrResult<String> {
+ let mut parts = head.trim_start_matches('$').split('.').peekable();
+ let mut focus = &LIBRARY.global;
+ while let Some(m) = parts.peek().and_then(|&name| get_module(focus, name).ok()) {
+ focus = m;
+ parts.next();
+ }
+
+ let name = parts.next().ok_or("link is missing first part")?;
+ let value = focus.field(name)?;
+ let Some(category) = focus.scope().get_category(name) else {
+ bail!("{name} has no category");
+ };
+
+ // Handle grouped functions.
+ if let Some(group) = GROUPS
+ .iter()
+ .filter(|_| category == "math")
+ .find(|group| group.functions.iter().any(|func| func == name))
+ {
+ let mut route =
+ format!("/docs/reference/math/{}/#functions-{}", group.name, name);
+ if let Some(param) = parts.next() {
+ route.push('-');
+ route.push_str(param);
+ }
+ return Ok(route);
+ }
+
+ let mut route = format!("/docs/reference/{category}/{name}/");
+ if let Some(next) = parts.next() {
+ if value.field(next).is_ok() {
+ route.push_str("#definitions-");
+ route.push_str(next);
+ } else if value
+ .clone()
+ .cast::<Func>()
+ .map_or(false, |func| func.param(next).is_some())
+ {
+ route.push_str("#parameters-");
+ route.push_str(next);
+ } else {
+ bail!("field {next} not found");
+ }
+ }
+
+ Ok(route)
+}
diff --git a/crates/typst-docs/src/model.rs b/crates/typst-docs/src/model.rs
new file mode 100644
index 00000000..46d979a2
--- /dev/null
+++ b/crates/typst-docs/src/model.rs
@@ -0,0 +1,170 @@
+use ecow::EcoString;
+use heck::ToKebabCase;
+use serde::Serialize;
+
+use crate::html::Html;
+
+/// Details about a documentation page and its children.
+#[derive(Debug, Serialize)]
+pub struct PageModel {
+ pub route: EcoString,
+ pub title: EcoString,
+ pub description: EcoString,
+ pub part: Option<&'static str>,
+ pub outline: Vec<OutlineItem>,
+ pub body: BodyModel,
+ pub children: Vec<Self>,
+}
+
+impl PageModel {
+ pub fn with_route(self, route: &str) -> Self {
+ Self { route: route.into(), ..self }
+ }
+
+ pub fn with_part(self, part: &'static str) -> Self {
+ Self { part: Some(part), ..self }
+ }
+}
+
+/// An element in the "On This Page" outline.
+#[derive(Debug, Clone, Serialize)]
+pub struct OutlineItem {
+ pub id: EcoString,
+ pub name: EcoString,
+ pub children: Vec<Self>,
+}
+
+impl OutlineItem {
+ /// Create an outline item from a name with auto-generated id.
+ pub fn from_name(name: &str) -> Self {
+ Self {
+ id: name.to_kebab_case().into(),
+ name: name.into(),
+ children: vec![],
+ }
+ }
+}
+
+/// Details about the body of a documentation page.
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+#[serde(tag = "kind", content = "content")]
+pub enum BodyModel {
+ Html(Html),
+ Category(CategoryModel),
+ Func(FuncModel),
+ Group(GroupModel),
+ Type(TypeModel),
+ Symbols(SymbolsModel),
+ Packages(Html),
+}
+
+/// Details about a category.
+#[derive(Debug, Serialize)]
+pub struct CategoryModel {
+ pub name: EcoString,
+ pub details: Html,
+ pub items: Vec<CategoryItem>,
+ pub shorthands: Option<ShorthandsModel>,
+}
+
+/// Details about a category item.
+#[derive(Debug, Serialize)]
+pub struct CategoryItem {
+ pub name: EcoString,
+ pub route: EcoString,
+ pub oneliner: EcoString,
+ pub code: bool,
+}
+
+/// Details about a function.
+#[derive(Debug, Serialize)]
+pub struct FuncModel {
+ pub path: Vec<EcoString>,
+ pub name: EcoString,
+ pub title: &'static str,
+ pub keywords: &'static [&'static str],
+ pub oneliner: &'static str,
+ pub element: bool,
+ pub details: Html,
+ /// This example is only for nested function models. Others can have
+ /// their example directly in their detals.
+ pub example: Option<Html>,
+ #[serde(rename = "self")]
+ pub self_: bool,
+ pub params: Vec<ParamModel>,
+ pub returns: Vec<&'static str>,
+ pub scope: Vec<FuncModel>,
+}
+
+/// Details about a function parameter.
+#[derive(Debug, Serialize)]
+pub struct ParamModel {
+ pub name: &'static str,
+ pub details: Html,
+ pub example: Option<Html>,
+ pub types: Vec<&'static str>,
+ pub strings: Vec<StrParam>,
+ pub default: Option<Html>,
+ pub positional: bool,
+ pub named: bool,
+ pub required: bool,
+ pub variadic: bool,
+ pub settable: bool,
+}
+
+/// A specific string that can be passed as an argument.
+#[derive(Debug, Serialize)]
+pub struct StrParam {
+ pub string: EcoString,
+ pub details: Html,
+}
+
+/// Details about a group of functions.
+#[derive(Debug, Serialize)]
+pub struct GroupModel {
+ pub name: EcoString,
+ pub title: EcoString,
+ pub details: Html,
+ pub functions: Vec<FuncModel>,
+}
+
+/// Details about a type.
+#[derive(Debug, Serialize)]
+pub struct TypeModel {
+ pub name: &'static str,
+ pub title: &'static str,
+ pub keywords: &'static [&'static str],
+ pub oneliner: &'static str,
+ pub details: Html,
+ pub constructor: Option<FuncModel>,
+ pub scope: Vec<FuncModel>,
+}
+
+/// A collection of symbols.
+#[derive(Debug, Serialize)]
+pub struct SymbolsModel {
+ pub name: &'static str,
+ pub details: Html,
+ pub list: Vec<SymbolModel>,
+}
+
+/// Details about a symbol.
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SymbolModel {
+ pub name: EcoString,
+ pub codepoint: u32,
+ pub accent: bool,
+ pub unicode_name: Option<EcoString>,
+ pub alternates: Vec<EcoString>,
+ pub markup_shorthand: Option<&'static str>,
+ pub math_shorthand: Option<&'static str>,
+}
+
+/// Shorthands listed on a category page.
+#[derive(Debug, Serialize)]
+pub struct ShorthandsModel {
+ pub markup: Vec<SymbolModel>,
+ pub math: Vec<SymbolModel>,
+}
generated by cgit v1.2.3 (git 2.25.1) at 2026-03-15 18:18:33 +0000