Doc: various doc improvements (#2)

samber · web-flow · commit a662a9305457 · 2025-10-14T21:04:29.000+02:00
* doc: fix code coverage url

* doc: add comparison between libraries

* feat: adding category intro page

* fix(doc): fix relative links

* doc: update readme
diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@
 [![GoDoc](https://godoc.org/github.com/samber/ro?status.svg)](https://pkg.go.dev/github.com/samber/ro)
 ![Build Status](https://github.com/samber/ro/actions/workflows/test.yml/badge.svg)
 [![Go report](https://goreportcard.com/badge/github.com/samber/ro)](https://goreportcard.com/report/github.com/samber/ro)
-[![Coverage](https://img.shields.io/codecov/c/github/samber/ro)](https://codecov.io/gh/samber/ro)
+[![Coverage](https://img.shields.io/codecov/c/github/samber/ro)](https://app.codecov.io/gh/samber/ro)
 [![Contributors](https://img.shields.io/github/contributors/samber/ro)](https://github.com/samber/ro/graphs/contributors)
 
 > A *Go* implementation of the [ReactiveX](https://reactivex.io/) spec.
@@ -45,9 +45,9 @@ Both libraries have `Map()`, `Filter()`... helpers. How are they different?
 | **Size**           | finite sequence             | infinite stream                                          |
 | **Flow control**   | pull-based (iterators)      | push-based                                               |
 
-`lo` is a bunch of helpers for looping across maps, slices...
+`lo` is a bunch of helpers for looping across finite sequences (maps, slices...)
 
-`ro` is focused on data processing of event-driven applications.
+`ro` is focused on processing of infinite data streams in event-driven applications.
 
 **Why this name?**
 
@@ -85,6 +85,8 @@ Now you discovered the paradigm, follow the documentation and turn reactive: [
 
 ## Core package
 
+Full documentation [here](https://ro.samber.dev/docs/operator).
+
 The `ro` library provides all basic operators:
 - **Creation operators**: The data source, usually the first argument of `ro.Pipe`
 - **Chainable operators**: They filter, validate, transform, enrich... messages
@@ -102,6 +104,8 @@ The `ro` library provides all basic operators:
 
 The `ro` library provides a rich ecosystem of plugins for various use cases:
 
+Full documentation [here](https://ro.samber.dev/docs/plugins).
+
 ### Data Manipulation
 - **Bytes** (`plugins/bytes`) - String and byte slice manipulation operators
 - **Strings** (`plugins/strings`) - String manipulation operators
diff --git a/docs/docs/about.md b/docs/docs/about.md
@@ -150,6 +150,6 @@ Designed for high-throughput scenarios:
 - **Data processing** with transformation, aggregation and enrichment
 - **Event-driven** patterns
 
-See [comparisons](./lo-vs-ro) with other Go libraries for more context.
+See [comparisons](./comparison/lo-vs-ro) with other Go libraries for more context.
 
 `ro` brings the elegance and power of reactive programming to Go while maintaining the language's core strengths of simplicity and performance.
diff --git a/docs/docs/comparison/_category_.json b/docs/docs/comparison/_category_.json
@@ -0,0 +1,8 @@
+{
+  "label": "📊 Comparison",
+  "position": 60,
+  "link": {
+    "type": "generated-index",
+    "description": "Compare samber/ro with other libraries"
+  }
+}
diff --git a/docs/docs/comparison/channels-vs-ro.md b/docs/docs/comparison/channels-vs-ro.md
@@ -1,5 +1,5 @@
 ---
-title: 📡 channels vs ro
+title: channels vs ro
 description: Compare Go channels vs samber/ro reactive streams
 sidebar_position: 3
 ---
@@ -594,7 +594,7 @@ The key performance difference is in backpressure handling:
 - **Channels**: Producer continues immediately after send, blocks only if buffer is full
 - **ro**: Producer waits until consumer completes processing before continuing
 
-Learn more about [backpressure](./glossary#Backpressure) in the glossary.
+Learn more about [backpressure](../glossary#Backpressure) in the glossary.
 
 :::
 
diff --git a/docs/docs/comparison/iter-vs-ro.md b/docs/docs/comparison/iter-vs-ro.md
@@ -1,5 +1,5 @@
 ---
-title: 🔁 iter vs ro
+title: iter vs ro
 description: Compare Go's iter package vs samber/ro reactive streams
 sidebar_position: 4
 ---
@@ -496,8 +496,8 @@ Go's `iter` package is excellent for synchronous iteration and sequences, while
 
 :::tip Learn More
 
-- Explore [Observable basics](./core/observable) for reactive concepts
-- Learn about [backpressure](./glossary#Backpressure) in reactive systems
-- Compare with [Go channels](./channels-vs-ro) for another concurrency approach
+- Explore [Observable basics](../core/observable) for reactive concepts
+- Learn about [backpressure](../glossary#Backpressure) in reactive systems
+- Compare with [Go channels](../comparison/channels-vs-ro) for another concurrency approach
 
 :::
diff --git a/docs/docs/comparison/lo-vs-ro.md b/docs/docs/comparison/lo-vs-ro.md
@@ -1,5 +1,5 @@
 ---
-title: ⚖️ samber/lo vs samber/ro
+title: samber/lo vs samber/ro
 description: Compare samber/lo (functional utils) vs samber/ro (reactive streams)
 sidebar_position: 5
 ---
@@ -286,8 +286,8 @@ Both libraries excel in their respective domains. Choose `lo` for traditional fu
 
 :::tip Learn More
 
-- Explore [samber/ro basics](./core/observable) for reactive concepts
-- See [Operators guide](./core/operators) for stream transformations
-- Learn about [backpressure](./glossary#Backpressure) in reactive systems
+- Explore [samber/ro basics](../core/observable) for reactive concepts
+- See [Operators guide](../core/operators) for stream transformations
+- Learn about [backpressure](../glossary#Backpressure) in reactive systems
 
 :::
diff --git a/docs/docs/core/observer.md b/docs/docs/core/observer.md
@@ -473,6 +473,6 @@ This fundamental difference affects how you design concurrent systems:
 - **Go channels**: Producer continues immediately, consumer processes asynchronously
 - **Observables**: Producer waits for consumer to finish, providing synchronous semantics
 
-See [Channels vs ro](../channels-vs-ro) for a detailed comparison.
+See [Channels vs ro](../comparison/channels-vs-ro) for a detailed comparison.
 
 Observers are the essential consumer interface in reactive programming, providing a clean, thread-safe way to handle streams of values with proper error handling and lifecycle management.
diff --git a/docs/docs/getting-started.md b/docs/docs/getting-started.md
@@ -444,7 +444,7 @@ Now that you understand the basics, explore:
 
 - **[Operators Reference](./operator/creation.md)**: Learn about all available operators
 - **[Examples]**: Check out practical examples in the examples directory
-- **[Comparison Guides](./lo-vs-ro)**: See how `samber/ro` compares to `channel`, `iter`, and `samber/lo`
+- **[Comparison Guides](./comparison/lo-vs-ro)**: See how `samber/ro` compares to `channel`, `iter`, and `samber/lo`
 - **[Advanced Patterns](./core/subject)**: `Subjects`, backpressure, and custom operators
 
 :::
diff --git a/docs/docs/operator/creation.md b/docs/docs/operator/creation.md
@@ -1,7 +1,7 @@
 ---
 title: Creation operators
 description: Create observables from values, iterables, timers, channels, and events.
-sidebar_position: 0
+sidebar_position: 1
 hide_table_of_contents: true
 ---
 
diff --git a/docs/docs/operator/index.md b/docs/docs/operator/index.md
@@ -0,0 +1,25 @@
+---
+title: Introduction
+description: Declarative and composable API
+sidebar_position: 0
+hide_table_of_contents: true
+---
+
+The `ro` library provides all basic operators:
+- **Creation operators**: The data source, usually the first argument of `ro.Pipe`
+- **Chainable operators**: They filter, validate, transform, enrich... messages
+  - **Transforming operators**: They transform items emitted by an `Observable`
+  - **Filtering operators**: They selectively emit items from a source `Observable`
+  - **Conditional operators**: Boolean operators
+  - **Math and aggregation operators**: They perform basic math operations
+  - **Error handling operators**: They help to recover from error notifications from an `Observable`
+  - **Combining operators**: Combine multiple `Observable` into one
+  - **Connectable operators**: Convert cold into hot `Observable`
+  - **Other**: manipulation of context, utility, async scheduling...
+- **Plugins**: External operators (mostly IOs and library wrappers)
+
+## Reference
+
+import DocCardList from '@theme/DocCardList';
+
+<DocCardList />
diff --git a/docs/docs/plugins/bytes.md b/docs/docs/plugins/bytes.md
@@ -1,7 +1,7 @@
 ---
 title: Bytes
 description: Byte manipulation and conversion utilities for observable streams.
-sidebar_position: 0
+sidebar_position: 1
 hide_table_of_contents: true
 ---
 
diff --git a/docs/docs/plugins/index.md b/docs/docs/plugins/index.md
@@ -0,0 +1,18 @@
+---
+title: Introduction
+description: Extend ro with powerful plugins for bytes, encoding, HTTP, observability, and more
+sidebar_position: 0
+hide_table_of_contents: true
+---
+
+# Plugins
+
+The `samber/ro` library comes with a rich ecosystem of plugins that extend its core functionality. These plugins provide specialized operators and utilities for common use cases like data encoding, HTTP requests, observability, file system operations, and much more.
+
+Each plugin is designed to be lightweight and focused on a specific domain, making it easy to add just the functionality you need to your reactive streams.
+
+## Reference
+
+import DocCardList from '@theme/DocCardList';
+
+<DocCardList />
diff --git a/docs/sidebars.ts b/docs/sidebars.ts
@@ -14,6 +14,9 @@ import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
  */
 const sidebars: SidebarsConfig = {
   // Enhanced sidebar with better organization and features from 3.8+
+
+  // docSidebar: [{type: 'autogenerated', dirName: '.'}],
+
   docSidebar: [
     'about',
     'getting-started',
@@ -29,6 +32,10 @@ const sidebars: SidebarsConfig = {
     {
       type: 'category',
       label: '👷 Operators',
+      link: {
+        type: 'doc',
+        id: 'operator/index',
+      },
       collapsible: true,
       collapsed: true,
       items: [
@@ -38,6 +45,10 @@ const sidebars: SidebarsConfig = {
     {
       type: 'category',
       label: '🔍 Plugins',
+      link: {
+        type: 'doc',
+        id: 'plugins/index',
+      },
       collapsible: true,
       collapsed: true,
       items: [
@@ -53,6 +64,18 @@ const sidebars: SidebarsConfig = {
         {type: 'autogenerated', dirName: 'troubleshooting'},
       ],
     },
+    {
+      type: 'category',
+      label: '📊 Comparison',
+      collapsible: true,
+      collapsed: true,
+      items: [
+        {type: 'autogenerated', dirName: 'comparison'},
+      ],
+    },
+    'testing',
+    'hacking',
+    'contributing',
     'glossary',
   ],
 };
diff --git a/docs/static/llms.txt b/docs/static/llms.txt
@@ -347,7 +347,7 @@ obs.Subscribe(ro.OnNext(func(msg string) {
 
 ## Comparison with other libraries
 
-`ro` vs `samber/lo`:
+`samber/ro` vs `samber/lo`:
 
 | Feature | `samber/lo` | `samber/ro` |
 |---------|-------------|-------------|
@@ -357,4 +357,6 @@ obs.Subscribe(ro.OnNext(func(msg string) {
 | Size | Finite sequences | Infinite streams |
 | Flow control | Pull-based (iterators) | Push-based |
 
-Use `lo` for in-memory data manipulation and `ro` for reactive, event-driven applications.
+`samber/lo` is a bunch of helpers for looping across finite sequences (maps, slices...)
+
+`samber/ro` is focused on processing of infinite data streams in event-driven applications.
