Initial docfx setup (#74)

* Initial DocFX setup and draft docs

* Added missing API index file

* Fixed access to internals

Noticed after generating API docs.

* Update .github/workflows/docs.yml

Co-authored-by: Caleb Lloyd <[email protected]>

* Update .github/workflows/docs.yml

Co-authored-by: Caleb Lloyd <[email protected]>

---------

Co-authored-by: Caleb Lloyd <[email protected]>

.github/workflows/docs.yml

@@ -0,0 +1,45 @@
+name: Docs
+
+on:
+  push:
+    branches:
+    - main
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+
+  github_pages:
+
+    name: docfx
+    runs-on: ubuntu-latest
+
+    steps:
+
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Setup dotnet
+        uses: actions/setup-dotnet@v3
+        with:
+          dotnet-version: '7.x'
+
+      - run: dotnet tool update -g docfx
+      - run: docfx docs/docfx.json
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: docs/_site
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

docs/.gitignore

@@ -0,0 +1,9 @@
+###############
+#    folder   #
+###############
+/**/DROP/
+/**/TEMP/
+/**/packages/
+/**/bin/
+/**/obj/
+

docs/api/.gitignore

@@ -0,0 +1,5 @@
+###############
+#  temp file  #
+###############
+*.yml
+.manifest

docs/api/index.md

@@ -0,0 +1,4 @@
+# API Documentation
+
+You can browse the latest NATS.NET V2 API Documentation here.
+API Documentation is auto-generated using [DocFX](https://dotnet.github.io/docfx/).

docs/docfx.json

@@ -0,0 +1,56 @@
+{
+  "metadata": [
+    {
+      "src": [
+        {
+          "files": [ "**/*.csproj" ],
+          "src": "../src"
+        }
+      ],
+      "dest": "api",
+      "includePrivateMembers": false,
+      "disableGitFeatures": false,
+      "disableDefaultFilter": false,
+      "noRestore": false,
+      "namespaceLayout": "flattened",
+      "memberLayout": "samePage",
+      "allowCompilationErrors": false
+    }
+  ],
+  "build": {
+    "content": [
+      {
+        "files": [
+          "api/**.yml",
+          "api/index.md"
+        ]
+      },
+      {
+        "files": [
+          "documentation/**.md",
+          "documentation/**/toc.yml",
+          "toc.yml",
+          "*.md"
+        ]
+      }
+    ],
+    "resource": [
+      {
+        "files": [
+          "images/**"
+        ]
+      }
+    ],
+    "output": "_site",
+    "globalMetadataFiles": [],
+    "fileMetadataFiles": [],
+    "template": [
+      "default",
+      "modern",
+      "nats_template"
+    ],
+    "postProcessors": [],
+    "keepFileLink": false,
+    "disableGitFeatures": false
+  }
+}

docs/documentation/intro.md

@@ -0,0 +1,9 @@
+# NATS.NET V2 Client
+
+NATS.NET V2 Client is a .Net client for the Open Source [Connective Technology for Adaptive Edge & Distributed Systems - NATS](https://nats.io/)!
+It's build on top of the modern .Net 6+ platform, taking advantage of all the high performance features and
+asynchronous programming model.
+
+NATS.NET V2 Client, just like NATS, is Open Source as is this documentation.
+Please [let us know](https://natsio.slack.com/channels/dotnet) if you have updates and/or suggestions for
+these docs. You can also create a Pull Request using the Edit on GitHub link on each page.

docs/documentation/pub-sub.md

@@ -0,0 +1,22 @@
+# Publish-Subscribe Pattern
+
+NATS implements a publish-subscribe message distribution model for one-to-many communication.
+A publisher sends a message on a subject and any active subscriber listening on that subject
+receives the message.
+
+```csharp
+await using var nats = new NatsConnection();
+
+await using sub = await nats.SubscribeAsync<int>("foo");
+
+for (int i = 0; i < 10; i++)
+{
+    Console.WriteLine($" Publishing {i}...");
+    await nats.PublishAsync<int>("foo", i);
+}
+
+await foreach (var msg in sub.Msgs.ReadAllAsync())
+{
+    Console.WriteLine($"Received {msg.Subject}: {msg.Data}\n");
+}
+```

docs/documentation/req-rep.md

@@ -0,0 +1,18 @@
+# Request-Reply Pattern
+
+Request-Reply is a common pattern in modern distributed systems.
+A request is sent, and the application either waits on the response with a certain timeout,
+or receives a response asynchronously.
+
+```csharp
+await using var nats = new NatsConnection();
+
+await using var replyHandle = await nats.ReplyAsync<int, string>("math.double", x =>
+{
+    Console.WriteLine($"Received request: {x}")
+    return $"Answer is: { 2 * x }";
+});
+
+var reply = await nats.RequestAsync<int, string>("math.double", 2);
+Console.WriteLine($"Received reply: {reply}")
+```

docs/documentation/toc.yml

@@ -0,0 +1,11 @@
+- name: Introduction
+  href: intro.md
+
+- name: Publish-Subscribe
+  href: pub-sub.md
+
+- name: Request-Reply
+  href: req-rep.md
+
+- name: Updating Documentation
+  href: update-docs.md

docs/documentation/update-docs.md

@@ -0,0 +1,20 @@
+# Updating Documentation
+
+As well as being able to edit pages on GitHub, you can also edit and update this documentation,
+view locally and submit a Pull Request to be included in this documentation site.
+
+## Runnig DocFX locally
+
+Clone the NATS.NET V2 repository, then run `docfx` local server to view this documentation site.
+You mush have [DocFX installed](https://dotnet.github.io/docfx/):
+
+```
+dotnet tool update -g docfx
+```
+
+Generate API documentation and run local server:
+```
+$ git clone https://github.com/nats-io/nats.net.v2.git
+$ cd nats.net.v2/docs
+$ docfx docfx.json --serve
+```

docs/index.md

@@ -0,0 +1,70 @@
+# NATS.NET V2 (Preview)
+
+The NATS.NET V2 client is in preview and not recommended for production use.
+Codebase is still under heavy development and currently we only have implementations for [core NATS](https://docs.nats.io/nats-concepts/core-nats) features.
+
+Please test and provide feedback by visiting our [Slack channel](https://natsio.slack.com/channels/dotnet).
+
+## NATS.NET V2 Goals
+
+- Only support Async I/O
+- Target latest .NET LTS Release (currently `net6.0`)
+
+## Packages
+
+- **NATS.Client.Core**: [core NATS](https://docs.nats.io/nats-concepts/core-nats)
+- **NATS.Client.Hosting**: extension to configure DI container
+- **NATS.Client.JetStream**: JetStream *not yet implemented*
+
+## Basic Usage
+
+[Download the latest](https://nats.io/download/) `nats-server` for your platform and run it without any arguments. `nats-server` will listen
+on its default TCP port 4222.
+
+Given that we have a plain class `Bar`, we can publish and subscribe to our `nats-server` sending
+and receiving `Bar` objects:
+
+```csharp
+public record Bar
+{
+    public int Id { get; set; }
+    public string Name { get; set; }
+}
+```
+
+Subscribe to all `bar` [related subjects](https://docs.nats.io/nats-concepts/subjects):
+```csharp
+await using var nats = new NatsConnection();
+
+await using sub = await nats.SubscribeAsync<Bar>("bar.>");
+await foreach (var msg in sub.Msgs.ReadAllAsync())
+{
+    Console.WriteLine($"Received {msg.Subject}: {msg.Data}\n");
+}
+```
+
+Publish `Bar` objects to related `bar` [subjects](https://docs.nats.io/nats-concepts/subjects):
+```csharp
+await using var nats = new NatsConnection();
+
+for (int i = 0; i < 10; i++)
+{
+    Console.WriteLine($" Publishing {i}...");
+    await nats.PublishAsync<Bar>($"bar.baz.{i}", new Bar { Id = i, Name = "Baz" });
+}
+```
+
+You should also hook your logger to `NatsConnection` to make sure all is working as expected or
+to get help diagnosing any issues you might have:
+```csharp
+var options = NatsOptions.Default with { LoggerFactory = new MinimumConsoleLoggerFactory(LogLevel.Error) };
+await using var nats = new NatsConnection(options);
+```
+
+## Contributing
+
+- Run `dotnet format` at root directory of project in order to clear warnings that can be auto-formatted
+
+## Attribution
+
+This library is based on the excellent work in [Cysharp/AlterNats](https://github.com/Cysharp/AlterNats)

docs/toc.yml

@@ -0,0 +1,12 @@
+- name: Documentation
+  href: documentation/
+
+- name: API
+  href: api/
+  homepage: api/index.md
+
+- name: GitHub
+  href: https://github.com/nats-io/nats.net.v2
+
+- name: Slack
+  href: https://natsio.slack.com/channels/dotnet

src/NATS.Client.Core/Commands/DirectWriteCommand.cs

@@ -4,7 +4,7 @@
 namespace NATS.Client.Core.Commands;
 
 // public for optimize reusing
-public sealed class DirectWriteCommand : ICommand
+internal sealed class DirectWriteCommand : ICommand
 {
     private readonly byte[] _protocol;
 

src/NATS.Client.Core/Internal/ISocketConnection.cs

@@ -1,6 +1,6 @@
 namespace NATS.Client.Core.Internal;
 
-public interface ISocketConnection : IAsyncDisposable
+internal interface ISocketConnection : IAsyncDisposable
 {
     public Task<Exception> WaitForClosed { get; }