Skip to content

Commit 3706c6f

Browse files
eabaeaba
authored
Added getting started to documentation (#5500)
* * Created getting-started sub-directory * Created Tutorial Overview * Moved all the Tutorials into getting-started sub-directory of intro * Fix linting issues * Fix linting issues * Resolves: 1. #5500 (comment) 2. #5500 (comment)
1 parent 2896372 commit 3706c6f

File tree

13 files changed

+128
-95
lines changed

13 files changed

+128
-95
lines changed

‎docs/articles/intro/getting-started/toc.yml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
- name: Tutorial Overview
2+
href: tutorial-overview.md
3+
- name: Part 1. Top-level Architecture
4+
href: tutorial-1.md
5+
- name: Part 2. The Device Actor
6+
href: tutorial-2.md
7+
- name: Part 3. Device Groups and Manager
8+
href: tutorial-3.md
9+
- name: Part 4. Querying a Group of Devices
10+
href: tutorial-4.md

‎docs/articles/intro/tutorial-1.md‎ renamed to ‎docs/articles/intro/getting-started/tutorial-1.md‎

Lines changed: 6 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -3,53 +3,7 @@ uid: tutorial-1
33
title: Part 1. Top-level Architecture
44
---
55

6-
# Part 1: Top-Level Architecture
7-
8-
In this and the following chapters, we will build a sample Akka.NET application
9-
to introduce you to the language of actors and how solutions can be formulated
10-
with them. It is a common hurdle for beginners to translate their project into
11-
actors even though they don't understand what they do on the high-level. We will
12-
build the core logic of a small application and this will serve as a guide for
13-
common patterns that will help to kickstart Akka.NET projects.
14-
15-
The application we aim to write will be a simplified IoT system where devices,
16-
installed at the home of users, can report temperature data from sensors. Users
17-
will be able to query the current state of these sensors. To keep things simple,
18-
we will not actually expose the application via HTTP or any other external API,
19-
we will, instead, concentrate only on the core logic. However, we will write
20-
tests for the pieces of the application to get comfortable and proficient with
21-
testing actors early on.
22-
23-
## Our Goals for the IoT System
24-
25-
We will build a simple IoT application with the bare essentials to demonstrate
26-
designing an Akka.NET-based system. The application will consist of two main
27-
components:
28-
29-
* **Device data collection:** This component has the responsibility to maintain
30-
a local representation of the otherwise remote devices. The devices will be
31-
organized into device groups, grouping together sensors belonging to a home.
32-
* **User dashboards:** This component has the responsibility to periodically
33-
collect data from the devices for a logged in user and present the results as
34-
a report.
35-
36-
For simplicity, we will only collect temperature data for the devices, but in a
37-
real application our local representations for a remote device, which we will
38-
model as an actor, would have many more responsibilities. Among others; reading
39-
the configuration of the device, changing the configuration, checking if the
40-
devices are unresponsive, etc. We leave these complexities for now as they can
41-
be easily added as an exercise.
42-
43-
We will also not address the means by which the remote devices communicate with
44-
the local representations (actors). Instead, we just build an actor based API
45-
that such a network protocol could use. We will use tests for our API everywhere
46-
though.
47-
48-
The architecture of the application will look like this:
49-
50-
![box diagram of the architecture](/images/arch_boxes_diagram.png)
51-
52-
## Top Level Architecture
6+
# Part 1: Top Level Architecture
537

548
When writing prose, the hardest part is usually to write the first couple of
559
sentences. There is a similar feeling when trying to build an Akka.NET system:
@@ -98,7 +52,7 @@ from user, or system, actors end up.
9852
> has. This special entity is called the "Bubble-Walker". This special entity is
9953
> invisible for the user and only has uses internally.
10054
101-
### Structure of an IActorRef and Paths of Actors
55+
## Structure of an IActorRef and Paths of Actors
10256

10357
The easiest way to see this in action is to simply print `IActorRef` instances.
10458
In this small experiment, we print the reference of the first actor we create
@@ -141,7 +95,7 @@ The last part of the actor reference, like `#1053618476` is a unique identifier
14195
of the actor living under the path. This is usually not something the user needs
14296
to be concerned with, and we leave the discussion of this field for later.
14397

144-
### Hierarchy and Lifecycle of Actors
98+
## Hierarchy and Lifecycle of Actors
14599

146100
We have so far seen that actors are organized into a **strict hierarchy**. This
147101
hierarchy consists of a predefined upper layer of three actors (the root
@@ -196,7 +150,7 @@ The family of these lifecycle hooks is rich, and we recommend reading [the actor
196150
lifecycle](xref:untyped-actor-api#actor-lifecycle) section of the reference for
197151
all details.
198152

199-
### Hierarchy and Failure Handling (Supervision)
153+
## Hierarchy and Failure Handling (Supervision)
200154

201155
Parents and children are not only connected by their lifecycles. Whenever an
202156
actor fails (throws an exception or an unhandled exception bubbles out from
@@ -240,7 +194,7 @@ see how the output changes.
240194
For the impatient, we also recommend looking into the [supervision reference
241195
page](xref:supervision) for more in-depth details.
242196

243-
### The First Actor
197+
## The First Actor
244198

245199
Actors are organized into a strict tree, where the lifecycle of every child is
246200
tied to the parent and where parents are responsible for deciding the fate of
@@ -280,7 +234,7 @@ All we need now is to tie this up with a class with the `main` entry point:
280234
This application does very little for now, but we have the first actor in place
281235
and we are ready to extend it further.
282236

283-
## What Is Next?
237+
# What Is Next?
284238

285239
In the following chapters we will grow the application step-by-step:
286240

‎docs/articles/intro/tutorial-2.md‎ renamed to ‎docs/articles/intro/getting-started/tutorial-2.md‎

File renamed without changes.

‎docs/articles/intro/tutorial-3.md‎ renamed to ‎docs/articles/intro/getting-started/tutorial-3.md‎

File renamed without changes.

‎docs/articles/intro/tutorial-4.md‎ renamed to ‎docs/articles/intro/getting-started/tutorial-4.md‎

File renamed without changes.

‎docs/articles/intro/getting-started/tutorial-overview.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
uid: tutorial-overview
3+
title: Tutorial Overview
4+
---
5+
6+
# Tutorial Overview
7+
8+
In this and the following chapters, we will build a sample Akka.NET application
9+
to introduce you to the language of actors and how solutions can be formulated
10+
with them. It is a common hurdle for beginners to translate their project into
11+
actors even though they don't understand what they do on the high-level. We will
12+
build the core logic of a small application and this will serve as a guide for
13+
common patterns that will help to kickstart Akka.NET projects.
14+
15+
The application we aim to write will be a simplified IoT system where devices,
16+
installed at the home of users, can report temperature data from sensors. Users
17+
will be able to query the current state of these sensors. To keep things simple,
18+
we will not actually expose the application via HTTP or any other external API,
19+
we will, instead, concentrate only on the core logic. However, we will write
20+
tests for the pieces of the application to get comfortable and proficient with
21+
testing actors early on.
22+
23+
## Our Goals for the IoT System
24+
25+
We will build a simple IoT application with the bare essentials to demonstrate
26+
designing an Akka.NET-based system. The application will consist of two main
27+
components:
28+
29+
* **Device data collection:** This component has the responsibility to maintain
30+
a local representation of the otherwise remote devices. The devices will be
31+
organized into device groups, grouping together sensors belonging to a home.
32+
* **User dashboards:** This component has the responsibility to periodically
33+
collect data from the devices for a logged in user and present the results as
34+
a report.
35+
36+
For simplicity, we will only collect temperature data for the devices, but in a
37+
real application our local representations for a remote device, which we will
38+
model as an actor, would have many more responsibilities. Among others; reading
39+
the configuration of the device, changing the configuration, checking if the
40+
devices are unresponsive, etc. We leave these complexities for now as they can
41+
be easily added as an exercise.
42+
43+
We will also not address the means by which the remote devices communicate with
44+
the local representations (actors). Instead, we just build an actor based API
45+
that such a network protocol could use. We will use tests for our API everywhere
46+
though.
47+
48+
The architecture of the application will look like this:
49+
50+
![box diagram of the architecture](/images/arch_boxes_diagram.png)
51+
52+
This tutorial is divided into four parts:
53+
54+
* [Part 1: Top-level Architecture](../getting-started/tutorial-1.html)
55+
* [Part 2. The Device Actor](../getting-started/tutorial-2.html)
56+
* [Part 3. Device Groups and Manager](../getting-started/tutorial-3.html)
57+
* [Part 4. Querying a Group of Devices](../getting-started/tutorial-4.html)

‎docs/articles/intro/toc.yml‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
- name: What is Akka.NET?
2+
href: what-is-akka.md
3+
- name: What problems does the actor model solve?
4+
href: what-problems-does-actor-model-solve.md
5+
- name: Akka.NET Libraries and Modules
6+
href: modules.md
7+
- name: Use-case and Deployment Scenarios
8+
href: use-case-and-deployment-scenarios.md
9+
- name: Production Users and Use Cases for Akka.NET
10+
href: akka-users.md
11+
- name: Getting Started
12+
href: getting-started/toc.yml

‎docs/articles/intro/tutorial-1.html‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
<!DOCTYPE html>
2+
<html>
3+
<head>
4+
<title>Part 1. Top-level Architecture</title>
5+
<meta http-equiv = "refresh" content="1;url=../intro/getting-started/tutorial-1.html" />
6+
</head>
7+
<body>
8+
<p>This page has been moved to <a href="../intro/getting-started/tutorial-1.html">Part 1. Top-level Architecture</a>.</p>
9+
</body>
10+
</html>

‎docs/articles/intro/tutorial-2.html‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
<!DOCTYPE html>
2+
<html>
3+
<head>
4+
<title>Part 2. The Device Actor</title>
5+
<meta http-equiv = "refresh" content="1;url=../intro/getting-started/tutorial-2.html" />
6+
</head>
7+
<body>
8+
<p>This page has been moved to <a href="../intro/getting-started/tutorial-2.html">Part 2. The Device Actor</a>.</p>
9+
</body>
10+
</html>

‎docs/articles/intro/tutorial-3.html‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
<!DOCTYPE html>
2+
<html>
3+
<head>
4+
<title>Part 3. Device Groups and Manager</title>
5+
<meta http-equiv = "refresh" content="1;url=../intro/getting-started/tutorial-3.html" />
6+
</head>
7+
<body>
8+
<p>This page has been moved to <a href="../intro/getting-started/tutorial-3.html">Part 3. Device Groups and Manager</a>.</p>
9+
</body>
10+
</html>

0 commit comments

Comments
 (0)