Updates in documentation

Writerside/lpk.tree

@@ -7,7 +7,7 @@
                  start-page="get-started.md">
 
     <toc-element topic="get-started.md"/>
-    <toc-element href="%api_reference%" toc-title="API Reference"/>
+    <toc-element href="%api_reference%" toc-title="API Reference" id="toc-api-reference"/>
     <toc-element topic="gallery.md"/>
     <toc-element topic="charts.md"/>
     <toc-element topic="whats_new.md"/>

Writerside/source/in-head.html

@@ -2,22 +2,32 @@
     document.addEventListener("DOMContentLoaded", onDOMContentLoaded);
 
     function onDOMContentLoaded() {
-        addGitHubLinkToHeader();
+        whenLoaded("header .wh-header a.wh-header__link").then(fixLogoLink);
+        whenLoaded("header .wh-header").then(addGitHubLinkToHeader);
+        whenLoaded("ul li[data-toc-scroll='toc-api-reference'] a").then(fixAPIReferenceTocLink);
     }
 
-    function addGitHubLinkToHeader() {
+    function fixLogoLink(linkElem) {
+        makeLinkInternal(linkElem);
+    }
+
+    function addGitHubLinkToHeader(headerElem) {
         function createGitHubLink() {
             const gitHubLinkElem = document.createElement("a");
             gitHubLinkElem.setAttribute("href", "https://github.com/JetBrains/lets-plot-kotlin");
             gitHubLinkElem.setAttribute("id", "github-repo-link");
+            gitHubLinkElem.setAttribute("target", "_blank");
             return gitHubLinkElem;
         }
 
-        whenLoaded("header .wh-header").then((headerElem) => {
-            const switchersElem = headerElem.querySelector(".wh-header__switchers");
-            const gitHubLinkElem = createGitHubLink();
-            headerElem.insertBefore(gitHubLinkElem, switchersElem);
-        });
+        const switchersElem = headerElem.querySelector(".wh-header__switchers");
+        const gitHubLinkElem = createGitHubLink();
+        headerElem.insertBefore(gitHubLinkElem, switchersElem);
+    }
+
+    function fixAPIReferenceTocLink(linkElem) {
+        const isInternal = makeLinkInternal(linkElem);
+        if (isInternal) linkElem.classList.remove("toc-item--external");
     }
 
     function whenLoaded(selector) {
@@ -37,6 +47,14 @@
             }
         });
     }
+
+    function makeLinkInternal(linkElem) {
+        const href = linkElem.getAttribute("href");
+        if (!href.startsWith("https://lets-plot.org")) return false;
+        linkElem.removeAttribute("target");
+        linkElem.dataset.test = linkElem.dataset.test.replace("external-link", "internal-link");
+        return true;
+    }
 </script>
 
 <style>

Writerside/topics/annotations.md

@@ -1,12 +1,31 @@
 # Annotating Charts
 
-You can customize the content of annotations for pie, bar and crossbar charts by using the `labels` parameter of the corresponding functions.
-The parameter takes as value the result of the [`layerLabels()`](%api_annotations%/layer-labels/index.html) function call.
+Lets-Plot provides several ways to annotate charts:
 
-[Learn more (datalore link)](%nbp-annotations%).
+- **Label annotations for geometry layers.**
+  Some geoms (such as pie, bar, and crossbar) support built-in text labels via the
+  `labels` parameter. Pass the result of the [`layerLabels()`](%api_annotations%/layer-labels/index.html)
+  call to configure the label content and layout.
 
-See also the [formatting reference](formats.md) to learn how to format numeric and date-time values in annotations.
+  [Learn more (reference notebook)](%nbp-annotations%).
+
+- **Annotations for** [`geomSmooth()`](%api_geom%/geom-smooth/index.html).
+  Use the `labels` parameter together with [`smoothLabels()`](%api_annotations%/smooth-labels/index.html)
+  to display statistics computed by the `smooth` stat (for example, R², adjusted R²,
+  and a fitted model equation). `smoothLabels` extends `layerLabels`, so formatting and text
+  template helpers work the same way.
+
+  [Learn more (reference notebook)](%nb-smooth_summary%).
 
+- **Bracket annotations.**
+  Use [`geomBracket()`](%api_geom%/geom-bracket/index.html) to add labeled brackets highlighting
+  relationships between categories or marking an interval.
+  Use [`geomBracketDodge()`](%api_geom%/geom-bracket-dodge/index.html) to draw brackets that connect
+  *dodged* groups within each category (e.g., comparisons inside grouped boxplots/bars).
+
+  [Learn more (reference notebook)](%nb-geom_bracket%).
+
+See also the [formatting reference](formats.md) to learn how to format numeric and date-time values in annotations.
 
 ## Examples
 

Writerside/topics/charts.md

@@ -113,6 +113,8 @@ Cookbooks:
 - [Lollipop plot](%nb-geom_lollipop%)
 - [Count stat](%nb-stat_count_2d%)
 - [Handling an overplotting on a scatter plot: `geomCount()`/`statSum()`](%nb-geom_count%)
+- [Generating color palettes with scale.palette()](%nb-scale_color_palette%)
+- [Handling color overflow in brewer palettes](%nb-scale_brewer_overflow%)
 - [Viridis colors](%nb-colors_viridis%)
 
 
@@ -231,6 +233,8 @@ Cookbooks:
 *Lets-Plot* handles all temporal data types through a unified "datetime" scale (excluding duration, which is handled by the "time" scale).
 This is in contrast to R's ggplot2, which provides separate "date", "time", and "datetime" scales.
 
+Use `breakWidth` in datetime and duration scales to control the axis break interval using human-readable strings like `"3 months"` or `"2 hours"`.
+
 **Supported temporal data types**:
 
 - `kotlinx.datetime` library:
@@ -257,6 +261,8 @@ Cookbooks:
 
 - [Scale time](%nb-scale_time%)
 - [Plotting time series](%nb-time_date_datetime%)
+- [`breakWidth` parameter in datetime scales](%nb-scale_break_width_datetime%)
+- [`breakWidth` parameter in time (duration) scales](%nb-scale_break_width_duration%)
 
 Demos:
 
@@ -273,6 +279,7 @@ Cookbooks:
 - [The `extent` parameter](%nb-image_extent%)
 - [Parameters `norm`, `vmain` and `vmax`](%nb-image_grayscale%)
 - ["Fisher boat": `geomImshow()` and raster data](%nb-image_fisher_boat%)
+- [Custom color palettes in `geomImshow()`](%nb-image_custom_cmap%)
 
 
 ## Coordinate Systems
@@ -289,6 +296,28 @@ Cookbooks:
 - [Polar coordinate system](%nb-coord_polar%)
 
 
+## Positional Scales
+
+[`scaleXDiscrete()`](%api_scale%/scale-x-discrete.html),
+[`scaleYDiscrete()`](%api_scale%/scale-y-discrete.html),
+[`scaleXDiscreteReversed()`](%api_scale%/scale-x-discrete-reversed.html),
+[`scaleYDiscreteReversed()`](%api_scale%/scale-y-discrete-reversed.html),
+[`scaleXContinuous()`](%api_scale%/scale-x-continuous.html),
+[`scaleYContinuous()`](%api_scale%/scale-y-continuous.html),
+[`scaleXLog10()`](%api_scale%/scale-x-log10.html),
+[`scaleYLog10()`](%api_scale%/scale-y-log10.html),
+[`scaleXLog2()`](%api_scale%/scale-x-log2.html),
+[`scaleYLog2()`](%api_scale%/scale-y-log2.html),
+[`scaleXReverse()`](%api_scale%/scale-x-reverse.html),
+[`scaleYReverse()`](%api_scale%/scale-y-reverse.html)
+
+Cookbooks:
+
+- [Axis position](%nb-axis_position%)
+- [`breakWidth` parameter in position scales](%nb-scale_break_width_log10%)
+- [Formatting labels on plots](%nb-formatting_axes_etc%)
+
+
 ## Legends and Guides
 
 [`guideLegend()`](%api_scale%/guide-legend.html),

Writerside/topics/formats.md

@@ -131,8 +131,8 @@ The number format can be used in a template to create a string with variable sub
 The string template contains “replacement fields” surrounded by curly braces `{}`.
 Anything that is not contained in braces is considered literal text, which is copied unchanged to the result string.
 If you need to include a brace character in the literal text, it can be escaped by doubling: `{{` and `}}`.
-This approach is used in functions [`layerTooltips()`](%api_tooltips%/layer-tooltips/index.html) and [`layerLabels()`](%api_annotations%/layer-labels/index.html)
-to customize the content of tooltips and annotations.
+This approach is used in functions [`layerTooltips()`](%api_tooltips%/layer-tooltips/index.html), [`layerLabels()`](%api_annotations%/layer-labels/index.html) and
+[`smoothLabels()`](%api_annotations%/smooth-labels/index.html) to customize the content of tooltips and annotations.
 
 See: [Tooltip Customization in Lets-Plot](tooltips.md) and [Annotating Charts in Lets-Plot](annotations.md).
 
@@ -239,7 +239,7 @@ To format the axis tooltips, follow the rules:
 
 ## Annotating Charts
 
-You can format text in annotations, see: [Annotating Charts](annotations.md).
+Use formatting in annotation labels and templates (e.g., via [`format()`](%api_tooltips%/layer-tooltips/format.html)); see: [Annotating Charts](annotations.md).
 
 ## Demo Notebooks
 

Writerside/topics/multiplot.md

@@ -29,4 +29,14 @@ Cookbooks:
 
 - [The `gggrid()` function](%nb-plot_grid%)
 - [Sharing X,Y-axis scale limits](%nb-gggrid_scale_share%)
-- [Collecting guides in gggrid()](%nb-gggrid_legend_collect%)
+- [Interactive pan/zoom with shared axes in gggrid](%nb-gggrid_scale_share_zoom%)
+- [Collecting guides in gggrid()](%nb-gggrid_legend_collect%)
+
+## Plot Tags
+
+Plot tags are short labels attached to subplots and composite figures (panel labels, figure numbering).
+Specify them via `labs(tag = ...)` and tune placement/style with `plotTag*` in [`theme()`](%api_theme%/theme/index.html).
+
+Cookbooks:
+
+- [Plot tags](%nb-plot_tags%)

Writerside/topics/whats_new.md

@@ -104,6 +104,6 @@
     </li>
 </list>
 
-## Change Log
+## Changelog
 
 See [CHANGELOG.md](https://github.com/JetBrains/lets-plot-kotlin/blob/master/CHANGELOG.md) for other changes and fixes.

Writerside/v.list

@@ -85,6 +85,7 @@
     <var name="nb-font_size_and_family" value="%nbviewer_cookbook%/font_size_and_family.ipynb"/>
     <var name="nb-formatting" value="%nbviewer_cookbook%/formatting.ipynb"/>
     <var name="nb-formatting_axes_etc" value="%nbviewer_cookbook%/formatting_axes_etc.ipynb"/>
+    <var name="nb-geom_bracket" value="%html_cookbook%/geom_bracket.html"/>
     <var name="nb-geom_count" value="%nbviewer_cookbook%/geom_count.ipynb"/>
     <var name="nb-geom_curve" value="%nbviewer_cookbook%/geom_curve.ipynb"/>
     <var name="nb-geom_dotplot" value="%nbviewer_cookbook%/geom_dotplot.ipynb"/>
@@ -101,14 +102,16 @@
     <var name="nb-geom_violin" value="%nbviewer_cookbook%/geom_violin.ipynb"/>
     <var name="nb-geom_ydotplot" value="%nbviewer_cookbook%/geom_ydotplot.ipynb"/>
     <var name="nb-ggbunch" value="%nbviewer_cookbook%/ggbunch.ipynb"/>
-    <var name="nb-ggrepel" value="%nbviewer_cookbook%/ggrepel.ipynb"/>
     <var name="nb-gggrid_legend_collect" value="%html_cookbook%/gggrid_legend_collect.html"/>
     <var name="nb-gggrid_scale_share" value="%nbviewer_cookbook%/gggrid_scale_share.ipynb"/>
+    <var name="nb-gggrid_scale_share_zoom" value="%html_cookbook%/gggrid_scale_share_zoom.html"/>
+    <var name="nb-ggrepel" value="%nbviewer_cookbook%/ggrepel.ipynb"/>
     <var name="nb-graph_edges" value="%nbviewer_cookbook%/graph_edges.ipynb"/>
     <var name="nb-group_override_defaults" value="%html_cookbook%/group_override_defaults.html"/>
     <var name="nb-hjust_vjust" value="%nbviewer_cookbook%/hjust_vjust.ipynb"/>
     <var name="nb-horizontal_geoms" value="%nbviewer_cookbook%/horizontal_geoms.ipynb"/>
     <var name="nb-image_101" value="%nbviewer_cookbook%/image_101.ipynb"/>
+    <var name="nb-image_custom_cmap" value="%html_cookbook%/image_custom_cmap.html"/>
     <var name="nb-image_extent" value="%nbviewer_cookbook%/image_extent.ipynb"/>
     <var name="nb-image_fisher_boat" value="%nbviewer_cookbook%/image_fisher_boat.ipynb"/>
     <var name="nb-image_grayscale" value="%nbviewer_cookbook%/image_grayscale.ipynb"/>
@@ -129,6 +132,7 @@
     <var name="nb-panel_border" value="%nbviewer_cookbook%/panel_border.ipynb"/>
     <var name="nb-param_width_unit" value="%nbviewer_cookbook%/param_width_unit.ipynb"/>
     <var name="nb-plot_grid" value="%nbviewer_cookbook%/plot_grid.ipynb"/>
+    <var name="nb-plot_tags" value="%html_cookbook%/plot_tags.html"/>
     <var name="nb-position_nudge_unit" value="%nbviewer_cookbook%/position_nudge_unit.ipynb"/>
     <var name="nb-position_stack" value="%nbviewer_cookbook%/position_stack.ipynb"/>
     <var name="nb-projection_provided" value="%nbviewer_cookbook%/projection_provided.ipynb"/>
@@ -141,10 +145,16 @@
     <var name="nb-ridgeline_plot" value="%nbviewer_cookbook%/ridgeline_plot.ipynb"/>
     <var name="nb-sampling_pick" value="%nbviewer_cookbook%/sampling_pick.ipynb"/>
     <var name="nb-sampling_stratified" value="%nbviewer_cookbook%/sampling_stratified.ipynb"/>
+    <var name="nb-scale_break_width_datetime" value="%html_cookbook%/scale_break_width_datetime.html"/>
+    <var name="nb-scale_break_width_duration" value="%html_cookbook%/scale_break_width_duration.html"/>
+    <var name="nb-scale_break_width_log10" value="%html_cookbook%/scale_break_width_log10.html"/>
+    <var name="nb-scale_brewer_overflow" value="%html_cookbook%/scale_brewer_overflow.html"/>
+    <var name="nb-scale_color_palette" value="%html_cookbook%/scale_color_palette.html"/>
     <var name="nb-scale_functions" value="%nbviewer_cookbook%/scale_functions.ipynb"/>
     <var name="nb-scale_time" value="%nbviewer_cookbook%/scale_time.ipynb"/>
     <var name="nb-scatter_plot" value="%nbviewer_cookbook%/scatter_plot.ipynb"/>
     <var name="nb-set_font_faces" value="%nbviewer_cookbook%/set_font_faces.ipynb"/>
+    <var name="nb-smooth_summary" value="%html_cookbook%/smooth_summary.html"/>
     <var name="nb-stat_boxplot_outlier" value="%nbviewer_cookbook%/stat_boxplot_outlier.ipynb"/>
     <var name="nb-stat_count_2d" value="%nbviewer_cookbook%/stat_count_2d.ipynb"/>
     <var name="nb-stat_ecdf" value="%nbviewer_cookbook%/stat_ecdf.ipynb"/>

devdocs/DOKKA_AND_WRITERSIDE.md

@@ -41,6 +41,10 @@ Now the documentation site can be explored locally with the [http-server](https:
 
 See: [Writerside: Configure search](https://www.jetbrains.com/help/writerside/configure-search.html#create-the-build-configuration-on-ci-cd)
 
+> [!IMPORTANT]
+> Always update the Algolia index after rebuilding and publishing the documentation,
+> regardless of the type or scope of the changes.
+
 - For the first run: add the Algolia admin secret API key (`aligola.key=`) to the [local.properties](../local.properties) file.
 
 - Run Bash script:

plot-api/build.gradle.kts

@@ -79,11 +79,11 @@ tasks.withType<org.jetbrains.dokka.gradle.DokkaTask>().configureEach {
             suppress.set(true)
         }
         perPackageOption {
-            matchingRegex.set(""".*\.intern.*""")
+            matchingRegex.set(""".*\.intern\..*""")
             suppress.set(true)
         }
         perPackageOption {
-            matchingRegex.set(""".*\.intern\.layer.*""")
+            matchingRegex.set(""".*\.intern\.layer(\..*)?""")
             suppress.set(false)
         }
     }

plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/annotations/AnnotationOptions.kt

@@ -23,12 +23,13 @@ typealias AnnotationOptions = layerLabels
  * contrast: white text appears on darker filled geometries, and black text
  * appears on lighter filled geometries.
  *
- * The text color can be manually specified using:
- * `theme(labelText=elementText(color=...))`
+ * Use `theme(labelText = elementText(color = ...))` to customize the appearance of annotation text.
+ * See also [elementText()][org.jetbrains.letsPlot.themes.elementText].
  *
- * Alternatively, the [inheritColor()][org.jetbrains.letsPlot.annotations.layerLabels.inheritColor] method can be used to override both
- * automatic and manual color settings, making the annotation text use the
- * geometry's `color` aesthetic instead.
+ * Alternatively, the [inheritColor()][org.jetbrains.letsPlot.annotations.layerLabels.inheritColor]
+ * method can be used to make annotation text use the geometry's `color` aesthetic,
+ * overriding both the automatically selected text color and any color specified via
+ * `theme(labelText = elementText(color = ...))`.
  *
  * ## Examples
  *