Export target docs (#5812)

Co-authored-by: Martin Haug <3874949+reknih@users.noreply.github.com>

3 files changed, 47 insertions, 55 deletions

diff --git a/crates/typst-library/src/foundations/mod.rs b/crates/typst-library/src/foundations/mod.rs
index c335484f..8e3aa060 100644
--- a/crates/typst-library/src/foundations/mod.rs
+++ b/crates/typst-library/src/foundations/mod.rs
@@ -85,16 +85,9 @@ use crate::engine::Engine;
 use crate::routines::EvalMode;
 use crate::{Feature, Features};
 
-/// Foundational types and functions.
-///
-/// Here, you'll find documentation for basic data types like [integers]($int)
-/// and [strings]($str) as well as details about core computational functions.
-#[category]
-pub static FOUNDATIONS: Category;
-
 /// Hook up all `foundations` definitions.
 pub(super) fn define(global: &mut Scope, inputs: Dict, features: &Features) {
-    global.start_category(FOUNDATIONS);
+    global.start_category(crate::Category::Foundations);
     global.define_type::<bool>();
     global.define_type::<i64>();
     global.define_type::<f64>();
@@ -125,6 +118,7 @@ pub(super) fn define(global: &mut Scope, inputs: Dict, features: &Features) {
     }
     global.define("calc", calc::module());
     global.define("sys", sys::module(inputs));
+    global.reset_category();
 }
 
 /// Fails with an error.
diff --git a/crates/typst-library/src/foundations/scope.rs b/crates/typst-library/src/foundations/scope.rs
index d6c5a8d0..e1ce61b8 100644
--- a/crates/typst-library/src/foundations/scope.rs
+++ b/crates/typst-library/src/foundations/scope.rs
@@ -1,6 +1,3 @@
-#[doc(inline)]
-pub use typst_macros::category;
-
 use std::fmt::{self, Debug, Formatter};
 use std::hash::{Hash, Hasher};
 
@@ -8,14 +5,13 @@ use ecow::{eco_format, EcoString};
 use indexmap::map::Entry;
 use indexmap::IndexMap;
 use typst_syntax::Span;
-use typst_utils::Static;
 
 use crate::diag::{bail, DeprecationSink, HintedStrResult, HintedString, StrResult};
 use crate::foundations::{
     Element, Func, IntoValue, NativeElement, NativeFunc, NativeFuncData, NativeType,
     Type, Value,
 };
-use crate::Library;
+use crate::{Category, Library};
 
 /// A stack of scopes.
 #[derive(Debug, Default, Clone)]
@@ -361,46 +357,6 @@ pub enum Capturer {
     Context,
 }
 
-/// A group of related definitions.
-#[derive(Copy, Clone, Eq, PartialEq, Hash)]
-pub struct Category(Static<CategoryData>);
-
-impl Category {
-    /// Create a new category from raw data.
-    pub const fn from_data(data: &'static CategoryData) -> Self {
-        Self(Static(data))
-    }
-
-    /// The category's name.
-    pub fn name(&self) -> &'static str {
-        self.0.name
-    }
-
-    /// The type's title case name, for use in documentation (e.g. `String`).
-    pub fn title(&self) -> &'static str {
-        self.0.title
-    }
-
-    /// Documentation for the category.
-    pub fn docs(&self) -> &'static str {
-        self.0.docs
-    }
-}
-
-impl Debug for Category {
-    fn fmt(&self, f: &mut Formatter) -> fmt::Result {
-        write!(f, "Category({})", self.name())
-    }
-}
-
-/// Defines a category.
-#[derive(Debug)]
-pub struct CategoryData {
-    pub name: &'static str,
-    pub title: &'static str,
-    pub docs: &'static str,
-}
-
 /// The error message when trying to mutate a variable from the standard
 /// library.
 #[cold]
diff --git a/crates/typst-library/src/foundations/target.rs b/crates/typst-library/src/foundations/target.rs
index 5841552e..2a21fd42 100644
--- a/crates/typst-library/src/foundations/target.rs
+++ b/crates/typst-library/src/foundations/target.rs
@@ -3,7 +3,7 @@ use comemo::Tracked;
 use crate::diag::HintedStrResult;
 use crate::foundations::{elem, func, Cast, Context};
 
-/// The compilation target.
+/// The export target.
 #[derive(Debug, Default, Copy, Clone, PartialEq, Hash, Cast)]
 pub enum Target {
     /// The target that is used for paged, fully laid-out content.
@@ -28,7 +28,49 @@ pub struct TargetElem {
     pub target: Target,
 }
 
-/// Returns the current compilation target.
+/// Returns the current export target.
+///
+/// This function returns either
+/// - `{"paged"}` (for PDF, PNG, and SVG export), or
+/// - `{"html"}` (for HTML export).
+///
+/// The design of this function is not yet finalized and for this reason it is
+/// guarded behind the `html` feature. Visit the [HTML documentation
+/// page]($html) for more details.
+///
+/// # When to use it
+/// This function allows you to format your document properly across both HTML
+/// and paged export targets. It should primarily be used in templates and show
+/// rules, rather than directly in content. This way, the document's contents
+/// can be fully agnostic to the export target and content can be shared between
+/// PDF and HTML export.
+///
+/// # Varying targets
+/// This function is [contextual]($context) as the target can vary within a
+/// single compilation: When exporting to HTML, the target will be `{"paged"}`
+/// while within an [`html.frame`].
+///
+/// # Example
+/// ```example
+/// #let kbd(it) = context {
+///   if target() == "html" {
+///     html.elem("kbd", it)
+///   } else {
+///     set text(fill: rgb("#1f2328"))
+///     let r = 3pt
+///     box(
+///       fill: rgb("#f6f8fa"),
+///       stroke: rgb("#d1d9e0b3"),
+///       outset: (y: r),
+///       inset: (x: r),
+///       radius: r,
+///       raw(it)
+///     )
+///   }
+/// }
+///
+/// Press #kbd("F1") for help.
+/// ```
 #[func(contextual)]
 pub fn target(context: Tracked<Context>) -> HintedStrResult<Target> {
     Ok(TargetElem::target_in(context.styles()?))