Skip to content

Commit

Permalink
Improve getting started doc section (#5689)
Browse files Browse the repository at this point in the history 
### What

* Fixes #5460

Various improvements to the getting started doc sections:
* better layout / new nesting structure
* improved titles, updated some references accordingly
* better & more complete install instructions
* remove 'Welcome' page, make index == new "What is Rerun?" page

⚠️ adds a placeholder page for getting started on blueprint


### Checklist
* [x] I have read and agree to [Contributor
Guide](https://github.com/rerun-io/rerun/blob/main/CONTRIBUTING.md) and
the [Code of
Conduct](https://github.com/rerun-io/rerun/blob/main/CODE_OF_CONDUCT.md)
* [x] I've included a screenshot or gif (if applicable)
* [x] I have tested the web demo (if applicable):
* Using newly built examples:
[app.rerun.io](https://app.rerun.io/pr/5689/index.html)
* Using examples from latest `main` build:
[app.rerun.io](https://app.rerun.io/pr/5689/index.html?manifest_url=https://app.rerun.io/version/main/examples_manifest.json)
* Using full set of examples from `nightly` build:
[app.rerun.io](https://app.rerun.io/pr/5689/index.html?manifest_url=https://app.rerun.io/version/nightly/examples_manifest.json)
* [x] The PR title and labels are set such as to maximize their
usefulness for the next release's CHANGELOG
* [x] If applicable, add a new check to the [release
checklist](https://github.com/rerun-io/rerun/blob/main/tests/python/release_checklist)!

- [PR Build Summary](https://build.rerun.io/pr/5689)
- [Docs
preview](https://rerun.io/preview/8a94f170002e4417e723545ef3005fc4b04966dc/docs)
<!--DOCS-PREVIEW-->
- [Examples
preview](https://rerun.io/preview/8a94f170002e4417e723545ef3005fc4b04966dc/examples)
<!--EXAMPLES-PREVIEW-->
- [Recent benchmark results](https://build.rerun.io/graphs/crates.html)
- [Wasm size tracking](https://build.rerun.io/graphs/sizes.html)

---------

Co-authored-by: Emil Ernerfeldt <emil.ernerfeldt@gmail.com>
  • Loading branch information
@Wumpf @emilk
Wumpf and emilk committed Mar 27, 2024
1 parent a1f59db commit bd2f64a
Show file tree
Hide file tree
Showing 19 changed files with 230 additions and 158 deletions.
10 changes: 1 addition & 9 deletions docs/content/getting-started.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,5 @@
---
title: Getting Started
order: 0
redirect: getting-started/what-is-rerun
---

Rerun currently works with both [Python](getting-started/logging-python.md) and [Rust](getting-started/logging-rust.md).
If you are looking for other language support, search for an open issue on [GitHub](https://github.com/rerun-io/rerun/issues) to find the status. If you can't find an issue for your language, [open one](https://github.com/rerun-io/rerun/issues/new/choose).

The fastest way to get started is with a quick start guide for [C++](getting-started/cpp.md), [Python](getting-started/python.md) or [Rust](getting-started/rust.md).

Many of our [examples](/examples) currently utilize Python. Even for
Rust users, these examples are a good way to get a sense of how Rerun works and how you might use it in your own
project.
12 changes: 12 additions & 0 deletions docs/content/getting-started/data-in.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
title: Get data into Rerun
order: 3
---

This section talks about how to get data out of your application into Rerun.

* Streaming data from your code
* [C++](./data-in/streaming/cpp.md)
* [Python](./data-in/streaming/python.md)
* [Rust](./data-in/streaming/rust.md)
* [Opening files](./data-in/open-any-file.md)
6 changes: 3 additions & 3 deletions docs/content/howto/open-any-file.md → .../getting-started/data-in/open-any-file.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Open any file
order: -10
title: Opening files
order: 1
---

The Rerun Viewer and SDK have built-in support for opening many kinds of files, and can be extended to support any other file type without needing to modify the Rerun codebase itself.
Expand Down Expand Up @@ -52,7 +52,7 @@ The easiest way to create your own `DataLoader` is by implementing what we call

This executable takes a file path as a command line argument and outputs Rerun logs on `stdout`.
It will be called by the Rerun Viewer/SDK when the user opens a file, and be passed the path to that file.
From there, it can log data as usual, using the [`stdout` logging sink](../reference/sdk-operating-modes.md#standard-inputoutput).
From there, it can log data as usual, using the [`stdout` logging sink](../../reference/sdk-operating-modes.md#standard-inputoutput).

The Rerun Viewer/SDK will then automatically load the data streamed to the external loader's standard output.

Expand Down
10 changes: 10 additions & 0 deletions docs/content/getting-started/data-in/streaming.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
title: Streaming data
order: 0
---

A step by step tutorial for how to stream data from your application to the Rerun viewer.

* [C++](./streaming/cpp.md)
* [Python](./streaming/python.md)
* [Rust](./streaming/rust.md)
26 changes: 13 additions & 13 deletions docs/content/getting-started/logging-cpp.md → .../getting-started/data-in/streaming/cpp.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: Logging Data in C++
title: C++
order: 5
---

Expand Down Expand Up @@ -34,7 +34,7 @@ build\Debug\example_dna.exe

## Prerequisites

You should have already [installed the viewer](installing-viewer.md).
You should have already [installed the viewer](../../installing-viewer.md).

We assume you have a working C++ toolchain and are using `CMake` to build your project. For this example
we will let Rerun download build [Apache Arrow](https://arrow.apache.org/)'s C++ library itself.
Expand Down Expand Up @@ -99,9 +99,9 @@ int main() {
}
```

Among other things, a stable `ApplicationId` will make it so the [Rerun Viewer](../reference/viewer/overview.md) retains its UI state across runs for this specific dataset, which will make our lives much easier as we iterate.
Among other things, a stable `ApplicationId` will make it so the [Rerun Viewer](../../../reference/viewer/overview.md) retains its UI state across runs for this specific dataset, which will make our lives much easier as we iterate.

Check out the reference to learn more about how Rerun deals with [applications and recordings](../concepts/apps-and-recordings.md).
Check out the reference to learn more about how Rerun deals with [applications and recordings](../../../concepts/apps-and-recordings.md).

## Testing our app

Expand Down Expand Up @@ -160,7 +160,7 @@ and now you should now see this scene in the viewer:
</picture>

_This is a good time to make yourself familiar with the viewer: try interacting with the scene and exploring the different menus._
_Checkout the [Viewer Walkthrough](viewer-walkthrough.md) and [viewer reference](../reference/viewer/overview.md) for a complete tour of the viewer's capabilities._
_Checkout the [Viewer Walkthrough](../../visualize/viewer-walkthrough.md) and [viewer reference](../../../reference/viewer/overview.md) for a complete tour of the viewer's capabilities._

## Under the hood

Expand All @@ -176,23 +176,23 @@ Under the hood, the Rerun C++ SDK logs individual *components* like positions, c
and radii. Archetypes are just one high-level, convenient way of building such collections of components. For advanced use
cases, it's possible to add custom components to archetypes, or even log entirely custom sets of components, bypassing
archetypes altogether.
For more information on how the rerun data model works, refer to our section on [Entities and Components](../concepts/entity-component.md).
For more information on how the rerun data model works, refer to our section on [Entities and Components](../../../concepts/entity-component.md).

Notably, the [`RecordingStream::log`](https://github.com/rerun-io/rerun/blob/d962b34b07775bbacf14883d683cca6746852b6a/rerun_cpp/src/rerun/recording_stream.hpp#L236) method
will handle any data type that implements the [`AsComponents<T>`](https://github.com/rerun-io/rerun/blob/latest/rerun_cpp/src/rerun/as_components.hpp) trait, making it easy to add your own data.
For more information on how to supply your own components see [Use custom data](../howto/extend/custom-data.md).
For more information on how to supply your own components see [Use custom data](../../../howto/extend/custom-data.md).

### Entities & hierarchies

Note the two strings we're passing in: `"dna/structure/left"` and `"dna/structure/right"`.

These are [*entity paths*](../concepts/entity-component.md), which uniquely identify each entity in our scene. Every entity is made up of a path and one or more components.
[Entity paths typically form a hierarchy](../concepts/entity-path.md) which plays an important role in how data is visualized and transformed (as we shall soon see).
These are [*entity paths*](../../../concepts/entity-component.md), which uniquely identify each entity in our scene. Every entity is made up of a path and one or more components.
[Entity paths typically form a hierarchy](../../../concepts/entity-path.md) which plays an important role in how data is visualized and transformed (as we shall soon see).

### Batches

One final observation: notice how we're logging a whole batch of points and colors all at once here.
[Batches of data](../concepts/batches.md) are first-class citizens in Rerun and come with all sorts of performance benefits and dedicated features.
[Batches of data](../../../concepts/batches.md) are first-class citizens in Rerun and come with all sorts of performance benefits and dedicated features.
You're looking at one of these dedicated features right now in fact: notice how we're only logging a single radius for all these points, yet somehow it applies to all of them. We call this *splatting*.

---
Expand Down Expand Up @@ -258,9 +258,9 @@ Once again, although we are getting fancier and fancier with our iterator mappin

### Introducing Time

Up until this point, we've completely set aside one of the core concepts of Rerun: [Time and Timelines](../concepts/timelines.md).
Up until this point, we've completely set aside one of the core concepts of Rerun: [Time and Timelines](../../../concepts/timelines.md).

Even so, if you look at your [Timeline View](../reference/viewer/timeline.md) right now, you'll notice that Rerun has kept track of time on your behalf anyway by memorizing when each log call occurred.
Even so, if you look at your [Timeline View](../../../reference/viewer/timeline.md) right now, you'll notice that Rerun has kept track of time on your behalf anyway by memorizing when each log call occurred.

<picture>
<source media="(max-width: 480px)" srcset="https://static.rerun.io/logging_data6_timeline/f22a3c92ae4f9f3a04901ec907a245e03e9dad68/480w.png">
Expand Down Expand Up @@ -390,4 +390,4 @@ You can also save a recording (or a portion of it) as you're visualizing it, dir

This closes our whirlwind tour of Rerun. We've barely scratched the surface of what's possible, but this should have hopefully given you plenty pointers to start experimenting.

As a next step, browse through our [example gallery](/examples) for some more realistic example use-cases, or browse the [Types](../reference/types.md) section for more simple examples of how to use the main data types.
As a next step, browse through our [example gallery](/examples) for some more realistic example use-cases, or browse the [Types](../../../reference/types.md) section for more simple examples of how to use the main data types.
28 changes: 14 additions & 14 deletions ...content/getting-started/logging-python.md → ...tting-started/data-in/streaming/python.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: Logging Data in Python
title: Python
order: 6
---

Expand All @@ -17,7 +17,7 @@ At any time, you can checkout the complete code listing for this tutorial [here]

## Prerequisites

We assume you have working Python and `rerun-sdk` installations. If not, check out the [setup page](python.md).
We assume you have working Python and `rerun-sdk` installations. If not, check out the [setup page](../../quick-start/python.md).

## Initializing the SDK

Expand All @@ -32,13 +32,13 @@ import rerun as rr
rr.init("rerun_example_dna_abacus")
```

Among other things, a stable [`ApplicationId`](https://ref.rerun.io/docs/python/stable/common/initialization_functions/#rerun.init) will make it so the [Rerun Viewer](../reference/viewer/overview.md) retains its UI state across runs for this specific dataset, which will make our lives much easier as we iterate.
Among other things, a stable [`ApplicationId`](https://ref.rerun.io/docs/python/stable/common/initialization_functions/#rerun.init) will make it so the [Rerun Viewer](../../../reference/viewer/overview.md) retains its UI state across runs for this specific dataset, which will make our lives much easier as we iterate.

Check out the reference to learn more about how Rerun deals with [applications and recordings](../concepts/apps-and-recordings.md).
Check out the reference to learn more about how Rerun deals with [applications and recordings](../../../concepts/apps-and-recordings.md).

## Starting the Viewer

Next up, we want to spawn the [Rerun Viewer](../reference/viewer/overview.md) itself.
Next up, we want to spawn the [Rerun Viewer](../../../reference/viewer/overview.md) itself.

To do this, you can add the line:
```python
Expand Down Expand Up @@ -95,7 +95,7 @@ rr.log("dna/structure/right", rr.Points3D(points2, colors=colors2, radii=0.08))
```

Run your script once again and you should now see this scene in the viewer.
Note that if the viewer was still running, Rerun will simply connect to this existing session and replace the data with this new [_recording_](../concepts/apps-and-recordings.md).
Note that if the viewer was still running, Rerun will simply connect to this existing session and replace the data with this new [_recording_](../../../concepts/apps-and-recordings.md).

<picture>
<img src="https://static.rerun.io/logging_data3_first_points/95c9c556160159eb2e47fb160ced89c899f2fcef/full.png" alt="">
Expand All @@ -108,7 +108,7 @@ Note that if the viewer was still running, Rerun will simply connect to this exi


_This is a good time to make yourself familiar with the viewer: try interacting with the scene and exploring the different menus._
_Checkout the [Viewer Walkthrough](viewer-walkthrough.md) and [viewer reference](../reference/viewer/overview.md) for a complete tour of the viewer's capabilities._
_Checkout the [Viewer Walkthrough](../../visualize/viewer-walkthrough.md) and [viewer reference](../../../reference/viewer/overview.md) for a complete tour of the viewer's capabilities._

## Under the hood

Expand All @@ -126,7 +126,7 @@ and radii. Archetypes are just one high-level, convenient way of building such c
cases, it's possible to add custom components to archetypes, or even log entirely custom sets of components, bypassing
archetypes altogether.

For more information on how the rerun data model works, refer to our section on [Entities and Components](../concepts/entity-component.md).
For more information on how the rerun data model works, refer to our section on [Entities and Components](../../../concepts/entity-component.md).

Our [Python SDK](https://ref.rerun.io/docs/python) integrates with the rest of the Python ecosystem: the points and colors returned by [`build_color_spiral`](https://ref.rerun.io/docs/python/stable/common/demo_utilities/#rerun.utilities.data.build_color_spiral) in this example are vanilla `numpy` arrays.
Rerun takes care of mapping those arrays to actual Rerun components depending on the context (e.g. we're calling [`rr.Points3D`](https://ref.rerun.io/docs/python/stable/common/archetypes/#rerun.archetypes.Points3D) in this case).
Expand All @@ -135,13 +135,13 @@ Rerun takes care of mapping those arrays to actual Rerun components depending on

Note the two strings we're passing in: `"dna/structure/left"` & `"dna/structure/right"`.

These are [*entity paths*](../concepts/entity-component.md), which uniquely identify each entity in our scene. Every entity is made up of a path and one or more components.
[Entity paths typically form a hierarchy](../concepts/entity-path.md) which plays an important role in how data is visualized and transformed (as we shall soon see).
These are [*entity paths*](../../../concepts/entity-component.md), which uniquely identify each entity in our scene. Every entity is made up of a path and one or more components.
[Entity paths typically form a hierarchy](../../../concepts/entity-path.md) which plays an important role in how data is visualized and transformed (as we shall soon see).

### Batches

One final observation: notice how we're logging a whole batch of points and colors all at once here.
[Batches of data](../concepts/batches.md) are first-class citizens in Rerun and come with all sorts of performance benefits and dedicated features.
[Batches of data](../../../concepts/batches.md) are first-class citizens in Rerun and come with all sorts of performance benefits and dedicated features.
You're looking at one of these dedicated features right now in fact: notice how we're only logging a single radius for all these points, yet somehow it applies to all of them. We call this *splatting*.

---
Expand Down Expand Up @@ -190,9 +190,9 @@ there is nothing new here: it's all about building out `numpy` arrays and feedin

### Introducing Time

Up until this point, we've completely set aside one of the core concepts of Rerun: [Time and Timelines](../concepts/timelines.md).
Up until this point, we've completely set aside one of the core concepts of Rerun: [Time and Timelines](../../../concepts/timelines.md).

Even so, if you look at your [Timeline View](../reference/viewer/timeline.md) right now, you'll notice that Rerun has kept track of time on your behalf anyway by memorizing when each log call occurred.
Even so, if you look at your [Timeline View](../../../reference/viewer/timeline.md) right now, you'll notice that Rerun has kept track of time on your behalf anyway by memorizing when each log call occurred.

<picture>
<source media="(max-width: 480px)" srcset="https://static.rerun.io/logging_data6_timeline/f22a3c92ae4f9f3a04901ec907a245e03e9dad68/480w.png">
Expand Down Expand Up @@ -321,4 +321,4 @@ You can also save a recording (or a portion of it) as you're visualizing it, dir

This closes our whirlwind tour of Rerun. We've barely scratched the surface of what's possible, but this should have hopefully given you plenty pointers to start experimenting.

As a next step, browse through our [example gallery](/examples) for some more realistic example use-cases, or browse the [Types](../reference/types.md) section for more simple examples of how to use the main datatypes.
As a next step, browse through our [example gallery](/examples) for some more realistic example use-cases, or browse the [Types](../../../reference/types.md) section for more simple examples of how to use the main datatypes.

0 comments on commit bd2f64a

Please sign in to comment.