From ad40efe8eb4771fdec714a859eb4c0598cda00a0 Mon Sep 17 00:00:00 2001 From: Manuel de la Pena Date: Thu, 29 Aug 2024 13:16:30 -0400 Subject: [PATCH] [Docs] Add intial docs. --- .github/workflows/deploy.yml | 41 +++++++++++++++++++++++++++++ docs/articles/fsevents_sample.md | 0 docs/articles/fswatcher.md | 0 docs/articles/toc.md | 7 +++++ docs/docfx.json | 45 ++++++++++++++++++++++++++++++++ src/Marille/Hub.cs | 16 ++++++++++++ src/Marille/IErrorWorker.cs | 16 ++++++++++++ src/Marille/WorkerError.cs | 5 ---- 8 files changed, 125 insertions(+), 5 deletions(-) create mode 100644 docs/articles/fsevents_sample.md create mode 100644 docs/articles/fswatcher.md create mode 100644 docs/articles/toc.md create mode 100644 docs/docfx.json delete mode 100644 src/Marille/WorkerError.cs diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index a2eb697..fdd930c 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -2,6 +2,16 @@ # deployes the build to nuget and github releases name: Continuous Deployment +concurrency: + group: "deployment" + cancel-in-progress: false + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + actions: read + pages: write + id-token: write + on: push: tags: @@ -48,6 +58,37 @@ jobs: retention-days: 7 path: ${{ env.NuGetDirectory }}/*.nupkg + publish-docs: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v3 + + - name: Setup .NET + uses: actions/setup-dotnet@v4 + with: + dotnet-version: 8.0.x + + - name: Install Docfx + run: dotnet tool update -g docfx + + - name: Run Docfx + run: docfx docs/docfx.json + + - name: Upload docs page + uses: actions/upload-pages-artifact@v3 + with: + path: 'docs/_site' + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 + validate-nuget: name: Validate nuget runs-on: ubuntu-latest diff --git a/docs/articles/fsevents_sample.md b/docs/articles/fsevents_sample.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/articles/fswatcher.md b/docs/articles/fswatcher.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/articles/toc.md b/docs/articles/toc.md new file mode 100644 index 0000000..184c639 --- /dev/null +++ b/docs/articles/toc.md @@ -0,0 +1,7 @@ +#[Introduction](intro.md) + +#Samples + +## [FSEvents](fsevents_sample.md) +## [FileSystemWatcher](fswatcher.md) + diff --git a/docs/docfx.json b/docs/docfx.json new file mode 100644 index 0000000..9d4bbab --- /dev/null +++ b/docs/docfx.json @@ -0,0 +1,45 @@ +{ + "metadata": [ + { + "src": [ + { + "src": "../src", + "files": [ + "**/Marille.csproj" + ] + } + ], + "dest": "api" + } + ], + "build": { + "content": [ + { + "files": [ + "**/*.{md,yml}" + ], + "exclude": [ + "_site/**" + ] + } + ], + "resource": [ + { + "files": [ + "images/**" + ] + } + ], + "output": "_site", + "template": [ + "default", + "modern" + ], + "globalMetadata": { + "_appName": "Marille", + "_appTitle": "Marille", + "_enableSearch": true, + "pdf": true + } + } +} diff --git a/src/Marille/Hub.cs b/src/Marille/Hub.cs index 25797ed..8977a41 100644 --- a/src/Marille/Hub.cs +++ b/src/Marille/Hub.cs @@ -210,6 +210,7 @@ bool TryGetChannel (string topicName, [NotNullWhen(true)] out Topic? topic, return true; } + /// public async Task CreateAsync (string topicName, TopicConfiguration configuration, IErrorWorker errorWorker, params IWorker[] initialWorkers) where T : struct { @@ -234,28 +235,34 @@ public async Task CreateAsync (string topicName, TopicConfiguration con } } + /// public Task CreateAsync (string topicName, TopicConfiguration configuration, IErrorWorker errorWorker, IEnumerable> initialWorkers) where T : struct => CreateAsync (topicName, configuration, errorWorker, initialWorkers.ToArray ()); + /// public Task CreateAsync (string topicName, TopicConfiguration configuration, Func errorAction, params Func [] actions) where T : struct => CreateAsync (topicName, configuration, new LambdaErrorWorker (errorAction), actions.Select (a => new LambdaWorker (a))); + /// public Task CreateAsync (string topicName, TopicConfiguration configuration, IErrorWorker errorWorker) where T : struct => CreateAsync (topicName, configuration, errorWorker, Array.Empty> ()); + /// public Task CreateAsync (string topicName, TopicConfiguration configuration, Func errorAction) where T : struct => CreateAsync (topicName, configuration, new LambdaErrorWorker (errorAction)); + /// public Task CreateAsync (string topicName, TopicConfiguration configuration, Func errorAction, Func action) where T : struct => CreateAsync (topicName, configuration, new LambdaErrorWorker (errorAction), new LambdaWorker (action)); + /// public async Task RegisterAsync (string topicName, params IWorker[] newWorkers) where T : struct { await semaphoreSlim.WaitAsync ().ConfigureAwait (false); @@ -279,9 +286,11 @@ public async Task RegisterAsync (string topicName, params IWorker[] } } + /// public Task RegisterAsync (string topicName, Func action) where T : struct => RegisterAsync (topicName, new LambdaWorker (action)); + /// public async ValueTask PublishAsync (string topicName, T publishedEvent) where T : struct { await semaphoreSlim.WaitAsync ().ConfigureAwait (false); @@ -296,12 +305,14 @@ public async ValueTask PublishAsync (string topicName, T publishedEvent) wher } } + /// public async ValueTask PublishAsync (string topicName, T? publishedEvent) where T : struct { if (publishedEvent is not null) await PublishAsync (topicName, publishedEvent.Value); } + /// public bool TryPublish (string topicName, T publishedEvent) where T : struct { semaphoreSlim.Wait (); @@ -316,12 +327,14 @@ public bool TryPublish (string topicName, T publishedEvent) where T : struct } } + /// public bool TryPublish (string topicName, T? publishedEvent) where T : struct { return publishedEvent is not null && TryPublish (topicName, publishedEvent.Value); } + /// public async Task CloseAllAsync () { // we are using this format to ensure that we have the right nullable types, if we where to use the following @@ -353,6 +366,7 @@ public async Task CloseAllAsync () } } + /// public async Task CloseAsync (string topicName) where T : struct { await semaphoreSlim.WaitAsync ().ConfigureAwait (false); @@ -386,6 +400,7 @@ protected virtual void Dispose (bool disposing) } } + /// public void Dispose () { Dispose (true); @@ -400,6 +415,7 @@ protected virtual async ValueTask DisposeAsyncCore () } } + /// public async ValueTask DisposeAsync () { await DisposeAsyncCore (); diff --git a/src/Marille/IErrorWorker.cs b/src/Marille/IErrorWorker.cs index a1e8ffc..e3e13c8 100644 --- a/src/Marille/IErrorWorker.cs +++ b/src/Marille/IErrorWorker.cs @@ -1,8 +1,24 @@ namespace Marille; +/// +/// Interface to be implemented by a worker that will take care of handling the errors from IWorker consumers in a +/// give channel. +/// +/// public interface IErrorWorker : IDisposable, IAsyncDisposable where T : struct { + /// + /// Specifies if the worker should use a background thread to process the messages. If set to + /// true the implementation of the worker should be thread safe. + /// public bool UseBackgroundThread { get; } + /// + /// + /// + /// + /// + /// + /// public Task ConsumeAsync (T message, Exception exception, CancellationToken token = default); } diff --git a/src/Marille/WorkerError.cs b/src/Marille/WorkerError.cs deleted file mode 100644 index 4b739c0..0000000 --- a/src/Marille/WorkerError.cs +++ /dev/null @@ -1,5 +0,0 @@ -namespace Marille; - -public class WorkerError { - public WorkerError(Type type, object worker, Exception? ex) {} -}