[DocFx] custom Akka.NET theme (#5659)

* added updated Akka.NET DocFx theme * added "Show and Tell" page * added v1.5 notes
akkadotnet · Mar 9, 2022 · 7123d0f · 7123d0f
1 parent 2e1d4ea
commit 7123d0f
Show file tree

Hide file tree

Showing 19 changed files with 1,971 additions and 8 deletions.
diff --git a/docs/articles/clustering/cluster-overview.md b/docs/articles/clustering/cluster-overview.md
@@ -11,7 +11,7 @@ A cluster represents a fault-tolerant, elastic, decentralized peer-to-peer netwo
 
 ## What Does Akka.Cluster Do?
 
-The best way to begin introducing Akka.Cluster is with brief overview of what it does. Akka.Cluster is the [package](https://www.nuget.org/packages/Akka.Cluster/1.0.3.11-beta) that brings clustering support to Akka.NET, and it accomplishes this by adding the following capabilities to Akka.NET:
+The best way to begin introducing Akka.Cluster is with brief overview of what it does. Akka.Cluster is the [package](https://www.nuget.org/packages/Akka.Cluster/) that brings clustering support to Akka.NET, and it accomplishes this by adding the following capabilities to Akka.NET:
 
 * Makes it easy to create peer-to-peer networks of Akka.NET applications
 * Allows peers to automatically discover new nodes and removed dead ones automatically with no configuration changes

diff --git a/docs/community/community-standups.md b/docs/community/community-standups.md
@@ -0,0 +1,68 @@
+---
+uid: community-standups
+title: Akka.NET Community Stand-Ups
+---
+
+# Akka.NET Community Stand-Ups
+
+Akka.NET Community Stand-ups are a once-a-month meeting that happens on the second Wednesday of each month and is live-streamed via [Petabridge’s YouTube channel](https://www.youtube.com/c/PetabridgeAcademy).
+
+> [!TIP]
+> [Click here to subscribe for future Akka.NET Community Stand-up notifications on YouTube](https://www.youtube.com/c/PetabridgeAcademy?sub_confirmation=1)
+
+## Structure of Each Stand-Up
+
+1. **Recap of most recent Akka.NET releases (10 min)** - we should talk about the work that was performed since the last stand-up, its impact on end-users, and what we learned in the course of performing that work.
+2. **Plans for future work (10 min)** - what are we working on next, why, and why should users care?
+3. **Opportunities to contribute (5 min)** - what help would we like from the Akka.NET end-user community?
+4. **Show and Tell (20 min)** - give members of the Akka.NET team and community opportunities to showcase their work built on top of Akka.NET.
+5. **Q&A (10 min)** - show and tell presenters along with the Akka.NET team should take questions via YouTube Live from the audience.
+
+### Current Schedule
+
+**Stand-ups are second Wednesday of each month starting at 12pm CST.**
+
+> [!TIP]
+> See our [schedule of upcoming 2022 Akka.NET Community Stand-ups here](https://github.com/akkadotnet/akka.net/discussions/5691).
+
+## Show and Tell Presentations
+
+The AKka.NET team features members of the Akka.NET community at each stand-up, where they their stories about how they use Akka.NET at work. e call these "Show and Tell" presentations and they are featured in our Community Stand-ups going forward.
+
+> [!IMPORTANT]
+> Show and Tell is a great way to attract talented .NET developers in the Akka.NET community who love to work on the sorts of interesting and important problems that Akka.NET solves well. Use this as a platform to showcase your company and attract great talent to it!
+
+You can participate in the Show and Tell process by filling out this form: [Akka.NET Community Stand-up Submission](https://forms.gle/zR1K2pygCFhdCG7v5) - someone from our team will respond, help you with your presentation, and get you scheduled for one of our upcoming 2022 Akka.NET Community Stand-ups.
+
+### Show and Tell Structure
+
+Show and tell is an important component of each set of community stand-ups as it gives members of the Akka.NET Community a chance to share their experiences and success with Akka.NET.
+
+Here is what makes for a compelling show and tell presentation:
+
+1. Presenter Background - who are you, who do you work for, and what do you do?
+2. Project Background - why is this project important to you and your company?
+3. Requirements - what requirements did this project have?
+4. Why Akka.NET - why did you choose Akka.NET? What was the criteria? What alternatives did you consider?
+5. Which parts of Akka.NET do you use and why?
+6. Was this a greenfield project or an update to a legacy system? What were the key implementation challenges with Akka.NET?
+7. How has the system been performing for you since?
+8. Visualization - do you have some diagrams that can help show how the system runs?
+9. Any future plans for Akka.NET on your project or at your company?
+
+### Production
+
+After you've submitted the form, a member of the Akka.NET team will contact you and help you put together a PowerPoint presentation or a live demo that helps "show" all of the answers to your questions above. This is a great opportunity for you and your company to showcase the interesting work that you do and attract potential Akka.NET talent to your company.
+
+### Past Show and Tells
+
+Examples of past show and tells:
+
+* [Game Plumbing Framework on Akka.NET](https://youtu.be/6AoDlK8LtFU?t=958) - July 7th, 2021
+
+### Submit a “Show and Tell”
+
+Want to share your experience with Akka.NET? Fill out our Google Form here and someone from our team will contact you about participating in an upcoming Akka.NET Community Stand-up!
+
+> [!TIP]
+> Click here to submit a "Show and Tell" proposal to the Akka.NET team: [Akka.NET Community Stand-up Submission](https://forms.gle/zR1K2pygCFhdCG7v5)
diff --git a/docs/community/toc.yml b/docs/community/toc.yml
@@ -2,6 +2,8 @@
   href: whats-new/toc.yml
 - name: Contributing to Akka.NET
   href: contributing/toc.yml
+- name: Community Standups
+  href: community-standups.md
 - name: Getting Access to Nightly Akka.NET Builds
   href: getting-access-to-nightly-builds.md
 - name: Online Resources

diff --git a/docs/community/whats-new/akkadotnet-v1.5.md b/docs/community/whats-new/akkadotnet-v1.5.md
@@ -0,0 +1,131 @@
+---
+uid: akkadotnet-v15-whats-new
+title: What's new in Akka.NET v1.5.0?
+---
+
+# Akka.NET v1.5 Plans and Goals
+
+Beginning with our [March 9th, 2022 Akka.NET Community Standup](xref:community-standups) we've shared our plans for the roadmap of Akka.NET v1.5.
+
+While not every technical detail is finalized yet, we do want to share the goals and some of the specific plans of what's included in this next minor version release of Akka.NET!
+
+## Goals
+
+<!-- markdownlint-disable MD033 -->
+<iframe width="560" height="315" src="https://www.youtube.com/embed/pZN1ugrJtJU" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+<!-- markdownlint-enable MD033 -->
+
+Based on feedback from Akka.NET users, here are the top priorities:
+
+1. **Better documentation and examples** - after simplifying the Akka.NET APIs around configuration and startup, modernizing all samples and deployment guidance is the biggest issue affecting end-users.
+2. **Improved Akka.Remote + Cluster.Sharding performance** - we want to go from ~350,000 msg/s to 1m+ msg/s in our `RemotePingPong` benchmark by changing the design of Akka.Remote's actors and optionally, replacing our transports.
+3. **Improved default serialization options** - Newtonsoft.Json sucks. Full stop.
+4. **Improved Akka.Cluster formation experience** - in layman's terms this means [releasing Akka.Management out of beta](https://github.com/akkadotnet/Akka.Management/discussions/417) and incorporating it into the Akka.Cluster literature and code samples.
+5. **Leveraging .NET 6+ primitives for improved performance** - thread execution, zero-allocation System.Memory data structures, and more.
+6. **Make CQRS a priority in Akka.Persistence** - tags are an especially weak area for Akka.Persistence right now, given that they require table scans.
+7. **Leverage Microsoft.Extensions more closely** - consume Microsoft.Extensions.Configuration from HOCON, allow Microsoft.Extensions.Logging interplay, and more.
+8. **Cleanup** - there are a lot of old constructs and that can be removed from Akka.NET.
+
+## How to Contribute
+
+Contributing to the v1.5 effort is somewhat different than our [normal maintenance contributions to Akka.NET](xref:contributing-to-akkadotnet),in the following ways:
+
+1. **Breaking binary compatibility changes are allowed so long as they are cost-justified** - contributors must be able to explain both the benefits and trade-offs involved in making this change in order for it to be accepted;
+2. **Wire compatibility must include a viable upgrade path** - if we're to introduce changes to the wire format of Akka.NET, contributors must demonstrate and document a viable upgrade path for end-users; and
+3. **Bigger bets are encouraged** - now is a good time to take some risks on the code base. So long as contributors can offer sound arguments for taking those bets (and this includes acknowledging and being realistic about trade-offs) then they should feel free to propose new changes that align with the 1.5 goals.
+
+### Good Areas for Contribution
+
+1. .NET 6 dual-targeting - there will be lots of areas where we can take advantage of new .NET 6 APIs for improved performance;
+2. Performance optimization - performance optimization around Akka.Remote, Akka.Persistence, Akka.Cluster.Sharding, DData, and core Akka will be prioritized in this release and there are _many_ areas for improvement;
+3. Akka.Hosting - there are lots of extension points and possibilities for making the APIs as expressive + concise as possible - we will need input from contributors to help make this possible;
+4. API Cleanup - there are lots of utility classes or deprecated APIs that can be deleted from the code base with minimal impact. Less is more; and
+5. New ideas and possibilities - this is a _great_ time to consider adding new features to Akka.NET. Be bold.
+
+> [!IMPORTANT]
+> Familiarize yourself with our [Akka.NET contribution guidelines](xref:contributing-to-akkadotnet) for best experience.
+
+## Designs & Major Changes
+
+### Akka.Hosting
+
+We want to make Akka.NET something that can be instantiated more typically per the patterns often used with the Microsoft.Extensions.Hosting APIs that are common throughout .NET.
+
+```csharp
+using Akka.Hosting;
+using Akka.Actor;
+using Akka.Actor.Dsl;
+using Akka.Cluster.Hosting;
+using Akka.Remote.Hosting;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddAkka("MyActorSystem", configurationBuilder =>
+{
+    configurationBuilder
+        .WithRemoting("localhost", 8110)
+        .WithClustering(new ClusterOptions(){ Roles = new[]{ "myRole" }, 
+            SeedNodes = new[]{ Address.Parse("akka.tcp://MyActorSystem@localhost:8110")}})
+        .WithActors((system, registry) =>
+    {
+        var echo = system.ActorOf(act =>
+        {
+            act.ReceiveAny((o, context) =>
+            {
+                context.Sender.Tell($"{context.Self} rcv {o}");
+            });
+        }, "echo");
+        registry.TryRegister<Echo>(echo); // register for DI
+    });
+});
+
+var app = builder.Build();
+
+app.MapGet("/", async (context) =>
+{
+    var echo = context.RequestServices.GetRequiredService<ActorRegistry>().Get<Echo>();
+    var body = await echo.Ask<string>(context.TraceIdentifier, context.RequestAborted).ConfigureAwait(false);
+    await context.Response.WriteAsync(body);
+});
+
+app.Run();
+```
+
+No HOCON. Automatically runs all Akka.NET application lifecycle best practices behind the scene. Automatically binds the `ActorSystem` and the `ActorRegistry`, another new 1.5 feature, to the `IServiceCollection` so they can be safely consumed via both actors and non-Akka.NET parts of users' .NET applications.
+
+This should be open to extension in other child plugins, such as Akka.Persistence.SqlServer:
+
+```csharp
+builder.Services.AddAkka("MyActorSystem", configurationBuilder =>
+{
+    configurationBuilder
+        .WithRemoting("localhost", 8110)
+        .WithClustering(new ClusterOptions()
+        {
+            Roles = new[] { "myRole" },
+            SeedNodes = new[] { Address.Parse("akka.tcp://MyActorSystem@localhost:8110") }
+        })
+        .WithSqlServerPersistence(builder.Configuration.GetConnectionString("sqlServerLocal"))
+        .WithShardRegion<UserActionsEntity>("userActions", s => UserActionsEntity.Props(s),
+            new UserMessageExtractor(),
+            new ShardOptions(){ StateStoreMode = StateStoreMode.DData, Role = "myRole"})
+        .WithActors((system, registry) =>
+        {
+            var userActionsShard = registry.Get<UserActionsEntity>();
+            var indexer = system.ActorOf(Props.Create(() => new Indexer(userActionsShard)), "index");
+            registry.TryRegister<Index>(indexer); // register for DI
+        });
+})
+```
+
+#### `ActorRegistry`
+
+As part of Akka.Hosting, we need to provide a means of making it easy to pass around top-level `IActorRef`s via dependency injection both within the `ActorSystem` and outside of it.
+
+The `ActorRegistry` will fulfill this role through a set of generic, typed methods that make storage and retrieval of long-lived `IActorRef`s easy and coherent:
+
+```csharp
+var registry = ActorRegistry.For(myActorSystem); // fetch from ActorSystem
+registry.TryRegister<Index>(indexer); // register for DI
+registry.Get<Index>(); // use in DI
+```
diff --git a/docs/community/whats-new/toc.yml b/docs/community/whats-new/toc.yml
@@ -1,3 +1,5 @@
+- name: New in Akka.NET v1.5
+  href: akkadotnet-v1.5.md
 - name: New in Akka.NET v1.4
   href: akkadotnet-v1.4.md
 - name: Upgrade Advisories (v1.4)

diff --git a/docs/docfx.json b/docs/docfx.json
@@ -67,7 +67,6 @@
             "_appTitle": "Akka.NET Documentation",
             "_appLogoPath": "/images/akkalogo.png",
             "_appFaviconPath": "/images/favicon.ico",
-            "_appFooter": "Copyright © 2013-2021 Akka.NET project<br>Generated by <strong>DocFX</strong>",
             "_enableSearch": "true"
         },
         "dest": "_site",

diff --git a/docs/images/footer.png b/docs/images/footer.png
diff --git a/docs/images/github.png b/docs/images/github.png
diff --git a/docs/images/header.svg b/docs/images/header.svg
diff --git a/docs/images/logos/petabridge_logo_full.png b/docs/images/logos/petabridge_logo_full.png
diff --git a/docs/images/logos/petabridge_square.png b/docs/images/logos/petabridge_square.png
diff --git a/docs/index.md b/docs/index.md
@@ -4,6 +4,7 @@ title: Akka.NET Documentation
 tagline: A straightforward approach to building distributed, high-scale applications in .NET
 ---
 <!-- markdownlint-disable MD033 -->
+<!-- markdownlint-disable MD009 -->
 <style>
 .subtitle {
     font-size:20px;
@@ -14,6 +15,9 @@ tagline: A straightforward approach to building distributed, high-scale applicat
 img.main-logo{
     width: 192px;
 }
+img.pb-logo-full{
+    width:  200px;
+}
 h2:before{
     display: none;
 }
@@ -23,18 +27,25 @@ h2:before{
 }
 </style>
 
-<div class="jumbotron">
-    <div class="container">
+<div class="container">
+    <div class="jumbotron">   
       <img src="images/mainlogo.png" class="main-logo" />
       <h1 class="title">Try <strong>Akka.NET</strong> now!</h1>
       <h1 class="title"><small class="subtitle">Follow our tutorial and build your first Akka.NET application today.</small></h1>
       <div class="options">
-        <a class="btn btn-lg btn-primary" href="community/whats-new/akkadotnet-v1.4.md">What's new in Akka.NET v1.4.0?</a>
+        <a class="btn btn-lg btn-primary" href="community/whats-new/akkadotnet-v1.5.md">Coming Soon: Akka.NET v1.5</a>
         <a class="btn btn-lg btn-primary" href="articles/intro/getting-started/tutorial-overview.md">Get Started Now</a> <a class="btn btn-lg btn-primary" href="articles/intro/what-is-akka.md">Read the documentation</a>
       </div>
     </div>
 </div>
 
+<div class="container">
+    <div class="row text-center">
+        <h2>Professionally Maintained and Supported by <a href="https://petabridge.com/" title="Petabridge - the Akka.NET Company">Petabridge</a></h2>
+         <a href="https://petabridge.com/" title="Petabridge - the Akka.NET Company"><img class="pb-logo-full" src="images/logos/petabridge_logo_full.png" alt="Petabridge, the Akka.NET Company."></a>
+    </div>
+</div>
+
 <section>
     <div class="container">
         <h2 class="lead">Build powerful concurrent &amp; distributed applications <strong>more easily</strong>.</h2>

diff --git a/docs/template/index.html.tmpl b/docs/template/index.html.tmpl
@@ -10,7 +10,7 @@
       <header>
         {{>partials/navbar}}
       </header>
-      <div class="container" style="margin-top:75px; padding-bottom:75px">
+      <div class="container-fluid" style="margin-top:75px; padding-bottom:75px">
           {{{conceptual}}}
       </div>
       {{>partials/footer}}

diff --git a/docs/template/layout/_master.tmpl b/docs/template/layout/_master.tmpl
@@ -0,0 +1,55 @@
+{{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}
+{{!include(/^styles/.*/)}}
+{{!include(/^fonts/.*/)}}
+{{!include(favicon.ico)}}
+{{!include(logo.svg)}}
+{{!include(search-stopwords.json)}}
+<!DOCTYPE html>
+<!--[if IE]><![endif]-->
+<html>
+  {{>partials/head}}
+  <body data-spy="scroll" data-target="#affix" data-offset="120">
+    <div id="wrapper" class="akka-net">
+      <header>
+        {{^_disableNavbar}}
+        {{>partials/navbar}}
+        {{/_disableNavbar}}
+        {{^_disableBreadcrumb}}
+        {{>partials/breadcrumb}}
+        {{/_disableBreadcrumb}}
+      </header>
+      {{#_enableSearch}}
+      <div class="container-fluid body-content viviek">
+        {{>partials/searchResults}}
+      </div>
+      {{/_enableSearch}}
+      <div role="main" class="container-fluid body-content hide-when-search">
+      {{^_disableToc}}
+        {{>partials/toc}}
+        <div class="article row grid-right">
+      {{/_disableToc}}
+      {{#_disableToc}}
+        <div class="article row grid">
+        {{/_disableToc}}
+          {{#_disableAffix}}
+          <div class="col-md-12">
+          {{/_disableAffix}}
+          {{^_disableAffix}}
+          <div class="col-md-10">
+          {{/_disableAffix}}
+            <article class="content wrap" id="_content" data-uid="{{uid}}">
+                {{!body}}
+            </article>
+          </div>
+          {{^_disableAffix}}
+          {{>partials/affix}}
+          {{/_disableAffix}}
+        </div>
+      </div>
+      {{^_disableFooter}}
+      {{>partials/footer}}
+      {{/_disableFooter}}
+    </div>
+    {{>partials/scripts}}
+  </body>
+</html>