Fixes and updates in the documentation (#282)

ASmirnov-HORIS · web-flow · commit ce52cb455ad6 · 2025-07-24T17:09:35.000+02:00
diff --git a/Writerside/cfg/buildprofiles.xml b/Writerside/cfg/buildprofiles.xml
@@ -1,8 +1,5 @@
 <buildprofiles xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/build-profiles.xsd"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
-    <variables>
-        <custom-css>custom.css</custom-css>
-    </variables>
     <variables>
         <web-root>https://lets-plot.org</web-root>
         <header-logo>logo-dark.svg</header-logo>
@@ -12,6 +9,7 @@
         <algolia-id>7961PKYRXV</algolia-id>
         <algolia-index>lets-plot-kotlin</algolia-index>
         <algolia-api-key>c281e6fa402631930df5a4d5baf863c5</algolia-api-key>
+        <custom-css>custom.css</custom-css>
     </variables>
     <footer>
         <copyright>2019-%current_year% JetBrains s.r.o.</copyright>
diff --git a/Writerside/images/plots/plot_layout_scheme.png b/Writerside/images/plots/plot_layout_scheme.png
diff --git a/Writerside/images/plots/theme_legend_scheme.png b/Writerside/images/plots/theme_legend_scheme.png
diff --git a/Writerside/images/previews/square-trading_chart.png b/Writerside/images/previews/square-trading_chart.png
diff --git a/Writerside/topics/charts.md b/Writerside/topics/charts.md
@@ -64,6 +64,8 @@ Examples:
 - [Inset map of Kotlin island](%nb-spatialdataset_kotlin_isl%)
 - [Drawing graph edges](%nb-graph_edges%)
 - [Formatting labels on plots](%nb-formatting_axes_etc%)
+- [Text geoms](%nb-text_geoms%)
+- [Repelled labels](%nb-ggrepel%)
 - [Variadic lines in `geomPath()` and `geomLine()`](%nb-aes_size_color_variadic_lines%)
 - [Spoke geometry](%nb-geom_spoke%)
 - [Curve geometry](%nb-geom_curve%)
@@ -90,6 +92,7 @@ Examples:
 
 - [Barchart](%nb-bar%)
 - [Pie-chart](%nb-geom_pie%)
+- [Combining discrete and continuous layers](%nb-numeric_data_on_discrete_scale%)
 - [Annotation labels on pie-chart](%nb-annotations_for_pie%)
 - [Annotated barchart](%nb-bar_annotations%)
 - ['boxplot_outlier' statistics](%nb-stat_boxplot_outlier%)
@@ -127,6 +130,7 @@ Examples:
 - [Dotplot geometry](%nb-geom_dotplot%)
 - [Y-Dotplot geometry](%nb-geom_ydotplot%)
 - [Violin plot](%nb-geom_violin%)
+- [Sina plot](%nb-geom_sina%)
 - [Ridgeline plot](%nb-ridgeline_plot%)
 - [The `orientation` parameter](%nb-y_orientation%)
 - [Parameter `threshold` in `geomHistogram()`](%nb-geom_histogram_threshold%)
@@ -164,7 +168,6 @@ Examples:
 Examples:
 
 - [Plotting means and error ranges](%nb-error_bars%)
-- [Horizontal error bars and vertical "dodge"](%nb-horizontal_error_bars%)
 - [Geometries with dual orientation](%nb-horizontal_geoms%)
 
 
diff --git a/Writerside/topics/formats.md b/Writerside/topics/formats.md
@@ -130,7 +130,7 @@ See more examples <a href="https://observablehq.com/@d3/d3-format">here</a>.
 The number format can be used in a template to create a string with variable substitution.
 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 }}.
+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.
 
diff --git a/Writerside/topics/gallery.md b/Writerside/topics/gallery.md
@@ -1,6 +1,11 @@
 # Gallery
 
 <list columns="3">
+    <li>
+        <a href="%nb-trading_chart%">
+            <img alt="Bitcoin daily trend visualization (2024)" src="square-trading_chart.png"/>
+        </a>
+    </li>
     <li>
         <a href="%nb-magnifier_inset%">
             <img alt="Creating magnifier inset effect with ggbunch()" src="square-magnifier_inset.png"/>
diff --git a/Writerside/topics/presentation_options.md b/Writerside/topics/presentation_options.md
@@ -73,4 +73,26 @@
 - [Theme flavors](%nb-theme_flavors%)
 - [Themes overview](%nb-themes%)
 - [Theme colors for geometries](%nb-geom_theme_colors%)
-- [Annotation labels on pie-chart](%nb-annotations_for_pie%)
+- [Annotation labels on pie-chart](%nb-annotations_for_pie%)
+
+## Plot Layout Diagrams
+
+These diagrams illustrate layout options and their spatial relationships within plot components.
+
+Option names on the diagrams (e.g., `axisTextSpacingX`) correspond to [`theme()`](%api_theme%/theme/index.html) function arguments.
+
+**Simple options** accept numeric values directly, e.g. `theme(axisTextSpacingX = 10)`.
+
+**Composite options** shown as `axisTitleX: Any?` accept [`elementText()`](%api_theme%/element-text.html) or [`elementRect()`](%api_theme%/element-rect.html) function results, e.g. `theme(axisTitleX = elementText(margin = listOf(5, 5)))`.
+
+### Plot Panel Layout
+
+<img src="plot_layout_scheme.png" alt="Plot layout scheme and theme parameters" style="block"/>
+
+The main plot area consists of nested elements such as the panel, axes, titles, and captions, each with configurable margins and spacing parameters.
+
+### Legend Box Layout
+
+<img src="theme_legend_scheme.png" alt="Theme legend scheme" style="block"/>
+
+The legend area consists of key-label pairs grouped into blocks, with configurable spacing between keys, labels, and blocks.
diff --git a/Writerside/v.list b/Writerside/v.list
@@ -41,6 +41,7 @@
     <var name="nb-spatialdataset_kotlin_isl" value="%nbviewer_demo%/spatialdataset_kotlin_isl.ipynb"/>
     <var name="nb-sunshine_hours" value="%nbviewer_demo%/sunshine_hours.ipynb"/>
     <var name="nb-theme_legend_scheme" value="%nbviewer_demo%/theme_legend_scheme.ipynb"/>
+    <var name="nb-trading_chart" value="%nbviewer_demo%/trading_chart.ipynb"/>
     <var name="nb-us_unemployment" value="%nbviewer_demo%/us_unemployment.ipynb"/>
     <var name="nb-wind_rose" value="%nbviewer_demo%/wind_rose.ipynb"/>
     <!-- Cookbooks -->
@@ -78,16 +79,17 @@
     <var name="nb-geom_histogram_threshold" value="%nbviewer_cookbook%/geom_histogram_threshold.ipynb"/>
     <var name="nb-geom_lollipop" value="%nbviewer_cookbook%/geom_lollipop.ipynb"/>
     <var name="nb-geom_pie" value="%nbviewer_cookbook%/geom_pie.ipynb"/>
+    <var name="nb-geom_sina" value="%nbviewer_cookbook%/geom_sina.ipynb"/>
     <var name="nb-geom_smooth" value="%nbviewer_cookbook%/geom_smooth.ipynb"/>
     <var name="nb-geom_spoke" value="%nbviewer_cookbook%/geom_spoke.ipynb"/>
     <var name="nb-geom_theme_colors" value="%nbviewer_cookbook%/geom_theme_colors.ipynb"/>
     <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_scale_share" value="%nbviewer_cookbook%/gggrid_scale_share.ipynb"/>
     <var name="nb-graph_edges" value="%nbviewer_cookbook%/graph_edges.ipynb"/>
     <var name="nb-hjust_vjust" value="%nbviewer_cookbook%/hjust_vjust.ipynb"/>
-    <var name="nb-horizontal_error_bars" value="%nbviewer_cookbook%/horizontal_error_bars.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_extent" value="%nbviewer_cookbook%/image_extent.ipynb"/>
@@ -104,6 +106,7 @@
     <var name="nb-margins" value="%nbviewer_cookbook%/margins.ipynb"/>
     <var name="nb-markdown" value="%nbviewer_cookbook%/markdown.ipynb"/>
     <var name="nb-multiple_color_scales" value="%nbviewer_cookbook%/multiple_color_scales.ipynb"/>
+    <var name="nb-numeric_data_on_discrete_scale" value="%nbviewer_cookbook%/numeric_data_on_discrete_scale.ipynb"/>
     <var name="nb-ordering_examples" value="%nbviewer_cookbook%/ordering_examples.ipynb"/>
     <var name="nb-panel_border" value="%nbviewer_cookbook%/panel_border.ipynb"/>
     <var name="nb-param_width_unit" value="%nbviewer_cookbook%/param_width_unit.ipynb"/>
diff --git a/docs/build_docs.sh b/docs/build_docs.sh
@@ -10,7 +10,7 @@ then
     exit 1
 fi
 
-docker_image="registry.jetbrains.team/p/writerside/builder/writerside-builder:241.16003"
+docker_image="registry.jetbrains.team/p/writerside/builder/writerside-builder:2025.04.8412"
 instance_id="lpk"
 
 root_path=$PWD
diff --git a/docs/update_algolia_index.sh b/docs/update_algolia_index.sh
@@ -14,7 +14,7 @@ algolia_app_name="7961PKYRXV"
 algolia_index_name="lets-plot-kotlin"
 config_json_product="kotlin"
 
-builder_docker_image="registry.jetbrains.team/p/writerside/builder/writerside-builder:241.16003"
+builder_docker_image="registry.jetbrains.team/p/writerside/builder/writerside-builder:2025.04.8412"
 algolia_publisher_docker_image="registry.jetbrains.team/p/writerside/builder/algolia-publisher:2.0.32-3"
 instance_id="lpk"
 
diff --git a/plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/geom/geom_boxplot.kt b/plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/geom/geom_boxplot.kt
@@ -89,11 +89,18 @@ import org.jetbrains.letsPlot.tooltips.TooltipOptions
  *  Defines the color aesthetic for the geometry.
  * @param fillBy default = "fill" ("fill", "color", "paint_a", "paint_b", "paint_c").
  *  Defines the fill aesthetic for the geometry.
- * @param lower Lower hinge, 25% quantile.
- * @param middle Median, 50% quantile.
- * @param upper Upper hinge, 75% quantile.
- * @param ymin Lower whisker - the smallest observation greater than or equal to the lower hinge - 1.5 * IQR
- * @param ymax Upper whisker - the largest observation less than or equal to the upper hinge + 1.5 * IQR
+ * @param x x-axis coordinate for vertical boxplot.
+ * @param lower Lower hinge, 25% quantile for vertical boxplot.
+ * @param middle Median, 50% quantile for vertical boxplot.
+ * @param upper Upper hinge, 75% quantile for vertical boxplot.
+ * @param ymin Lower whisker - the smallest observation greater than or equal to the lower hinge - 1.5 * IQR for vertical boxplot.
+ * @param ymax Upper whisker - the largest observation less than or equal to the upper hinge + 1.5 * IQR for vertical boxplot.
+ * @param y y-axis coordinate for horizontal boxplot.
+ * @param xlower Lower hinge, 25% quantile for horizontal boxplot.
+ * @param xmiddle Median, 50% quantile for horizontal boxplot.
+ * @param xupper Upper hinge, 75% quantile for horizontal boxplot.
+ * @param xmin Lower whisker - the smallest observation greater than or equal to the lower hinge - 1.5 * IQR for horizontal boxplot.
+ * @param xmax Upper whisker - the largest observation less than or equal to the upper hinge + 1.5 * IQR for horizontal boxplot.
  * @param width Width of boxplot. Typically ranges between 0 and 1. Values that are greater than 1 lead to overlapping of the boxes.
  * @param alpha Transparency level of a layer.
  *  Understands numbers between 0 and 1.
diff --git a/plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/stat/stat_boxplot.kt b/plot-api/src/commonMain/kotlin/org/jetbrains/letsPlot/stat/stat_boxplot.kt
@@ -45,13 +45,18 @@ import org.jetbrains.letsPlot.pos.positionDodge
  * @param sampling Result of the call to the `samplingXxx()` function.
  *  To prevent any sampling for this layer pass value `samplingNone`.
  *  For more info see [sampling.html](https://lets-plot.org/kotlin/sampling.html).
- * @param x X-axis value.
- * @param y Y-axis value.
- * @param lower Lower hinge, 25% quantile.
- * @param middle Median, 50% quantile.
- * @param upper Upper hinge, 75% quantile.
- * @param ymin Lower whisker - the smallest observation greater than or equal to the lower hinge - 1.5 * IQR
- * @param ymax Upper whisker - the largest observation less than or equal to the upper hinge + 1.5 * IQR
+ * @param x X-axis value for vertical boxplot.
+ * @param lower Lower hinge, 25% quantile for vertical boxplot.
+ * @param middle Median, 50% quantile for vertical boxplot.
+ * @param upper Upper hinge, 75% quantile for vertical boxplot.
+ * @param ymin Lower whisker - the smallest observation greater than or equal to the lower hinge - 1.5 * IQR for vertical boxplot.
+ * @param ymax Upper whisker - the largest observation less than or equal to the upper hinge + 1.5 * IQR for vertical boxplot.
+ * @param y Y-axis value for horizontal boxplot.
+ * @param xlower Lower hinge, 25% quantile for horizontal boxplot.
+ * @param xmiddle Median, 50% quantile for horizontal boxplot.
+ * @param xupper Upper hinge, 75% quantile for horizontal boxplot.
+ * @param xmin Lower whisker - the smallest observation greater than or equal to the lower hinge - 1.5 * IQR for horizontal boxplot.
+ * @param xmax Upper whisker - the largest observation less than or equal to the upper hinge + 1.5 * IQR for horizontal boxplot.
  * @param alpha Transparency level of a layer.
  *  Understands numbers between 0 and 1.
  * @param color Color of the geometry.
