From b3c6a065001c2aba05abf56f2c3e0a4838ef90d4 Mon Sep 17 00:00:00 2001 From: Christopher F Date: Mon, 3 Apr 2017 16:26:29 -0400 Subject: [PATCH] Revamp docs page on logging --- docs/CONTRIBUTING.md | 40 +++++++++++++++++++++++++++---- docs/docfx.json | 3 ++- docs/guides/installing.md | 2 +- docs/guides/intro.md | 7 ++++-- docs/guides/logging.md | 43 +++++++++++++++++++++++++++++----- docs/guides/samples/logging.cs | 41 ++++++++++++++++---------------- 6 files changed, 101 insertions(+), 35 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index f19e7c297..695475dfa 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,15 +1,45 @@ # Contributing to Docs -I don't really have any strict conditions for writing documentation, but just keep these few guidelines in mind: +I don't really have any strict conditions for writing documentation, +but just keep these few guidelines in mind: * Keep code samples in the `guides/samples` folder -* When referencing an object in the API, link to it's page in the API documentation. +* When referencing an object in the API, link to it's page in the +API documentation. * Documentation should be written in clear and proper English* -\* If anyone is interested in translating documentation into other languages, please open an issue or contact me on Discord (`foxbot#0282`). +\* If anyone is interested in translating documentation into other +languages, please open an issue or contact me on +Discord (`foxbot#0282`). + +### Layout + +Documentation should be written in a FAQ/Wiki style format. + +Recommended reads: + +* http://docs.microsoft.com +* http://flask.pocoo.org/docs/0.12/ + +Style consistencies: + +* Use a ruler set at 70 characters +* Links should use long syntax + +Example of long link syntax: + +``` +Please consult the [API Documentation] for more information. + +[API Documentation]: xref:System.String +``` ### Compiling -Documentation is compiled into a static site using [DocFx](https://dotnet.github.io/docfx/). We currently use version 2.8 +Documentation is compiled into a static site using [DocFx]. +We currently use the most recent build off the dev branch. + +After making changes, compile your changes into the static site with +`docfx`. You can also view your changes live with `docfx --serve`. -After making changes, compile your changes into the static site with `docfx`. You can also view your changes live with `docfx --serve`. \ No newline at end of file +[DocFx]: https://dotnet.github.io/docfx/ \ No newline at end of file diff --git a/docs/docfx.json b/docs/docfx.json index 42d6bbfee..3c0b0611e 100644 --- a/docs/docfx.json +++ b/docs/docfx.json @@ -42,7 +42,8 @@ "resource": [ { "files": [ - "images/**" + "**/images/**", + "**/samples/**" ], "exclude": [ "obj/**", diff --git a/docs/guides/installing.md b/docs/guides/installing.md index fa1280929..02c7cdab7 100644 --- a/docs/guides/installing.md +++ b/docs/guides/installing.md @@ -11,7 +11,7 @@ Optionally, you may compile from source and install yourself. Currently, Discord.Net targets [.NET Standard] 1.3, and offers support for .NET Standard 1.1. If your application will be targeting .NET Standard 1.1, -please see the [additional steps](#installing-on-.net-standard-11). +please see the [additional steps](#installing-on-net-standard-11). Since Discord.Net is built on the .NET Standard, it is also recommended to create applications using [.NET Core], though you are not required to. When diff --git a/docs/guides/intro.md b/docs/guides/intro.md index 314f2c32e..e0b41e22a 100644 --- a/docs/guides/intro.md +++ b/docs/guides/intro.md @@ -34,7 +34,9 @@ through the OAuth2 flow. 1. Open your bot's application on the [Discord Applications Portal] 2. Retrieve the app's **Client ID**. + ![Step 2](images/intro-client-id.png) + 3. Create an OAuth2 authorization URL `https://discordapp.com/oauth2/authorize?client_id=&scope=bot` 4. Open the authorization URL in your browser @@ -45,6 +47,7 @@ Only servers where you have the `MANAGE_SERVER` permission will be present in this list. 6. Click authorize + ![Step 6](images/intro-add-bot.png) ## Connecting to Discord @@ -120,7 +123,7 @@ on your bot's application page on the [Discord Applications Portal]). >[!IMPORTANT] Your bot's token can be used to gain total access to your bot, so -**do __NOT__ share this token with anyone!**. It may behoove you to +**do __NOT__ share this token with anyone!** It may behoove you to store this token in an external file if you plan on distributing the source code for your bot. @@ -157,7 +160,7 @@ for how to fix this. [TAP]: https://docs.microsoft.com/en-us/dotnet/articles/csharp/async [API Documentation]: xref:Discord.Rest.BaseDiscordClient#Discord_Rest_BaseDiscordClient_Log [DiscordSocketClient]: xref:Discord.WebSocket.DiscordSocketClient -[installing guide]: installing.md#installing-on-.net-standard-11 +[installing guide]: installing.md#installing-on-net-standard-11 ### Handling a 'ping' diff --git a/docs/guides/logging.md b/docs/guides/logging.md index 97fed3a52..1592dfc72 100644 --- a/docs/guides/logging.md +++ b/docs/guides/logging.md @@ -1,11 +1,42 @@ -# Using the Logger +--- +title: Logging +--- -Discord.Net will automatically output log messages through the [Log](xref:Discord.DiscordClient#Discord_DiscordClient_Log) event. +Discord.Net's clients provide a [Log] event that all messages will be +disbatched over. -## Usage +For more information about events in Discord.Net, see the [Events] +section. -To handle Log Messages through Discord.Net's Logger, hook into the [Log](xref:Discord.DiscordClient#Discord_DiscordClient_Log) event. +[Log]: xref:Discord.Rest.BaseDiscordClient#Discord_Rest_BaseDiscordClient_Log +[Events]: events.md -The @Discord.LogMessage object has a custom `ToString` method attached to it, when outputting log messages, it is reccomended you use this, instead of building your own output message. +### Usage -[!code-csharp[](samples/logging.cs)] \ No newline at end of file +To receive log events, simply hook the discord client's log method +to a Task with a single parameter of type [LogMessage] + +It is recommended that you use an established function instead of a +lambda for handling logs, because most [addons] accept a reference +to a logging function to write their own messages. + +### Usage in Commands + +Discord.Net's [CommandService] also provides a log event, identical +in signature to other log events. + +Data logged through this event is typically coupled with a +[CommandException], where information about the command's context +and error can be found and handled. + +#### Samples + +[!code-csharp[Logging Sample](samples/logging.cs)] + +#### Tips + +Due to the nature of Discord.Net's event system, all log event +handlers will be executed synchronously on the gateway thread. If your +log output will be dumped to a Web API (e.g. Sentry), you are advised +to wrap your output in a `Task.Run` so the gateway thread does not +become blocked while waiting for logging data to be written. \ No newline at end of file diff --git a/docs/guides/samples/logging.cs b/docs/guides/samples/logging.cs index fd72daf2b..a2ddf7b90 100644 --- a/docs/guides/samples/logging.cs +++ b/docs/guides/samples/logging.cs @@ -1,28 +1,29 @@ using Discord; -using Discord.Rest; +using Discord.WebSocket; public class Program { - private DiscordSocketClient _client; - static void Main(string[] args) => new Program().Start().GetAwaiter().GetResult(); - - public async Task Start() - { - _client = new DiscordSocketClient(new DiscordSocketConfig() { + private DiscordSocketClient _client; + static void Main(string[] args) => new Program().MainAsync().GetAwaiter().GetResult(); + + public async Task MainAsync() + { + _client = new DiscordSocketClient(new DiscordSocketConfig + { LogLevel = LogSeverity.Info - }); + }); - _client.Log += Log; + _client.Log += Log; - await _client.LoginAsync(TokenType.Bot, "bot token"); - await _client.ConnectAsync(); - - await Task.Delay(-1); - } + await _client.LoginAsync(TokenType.Bot, "bot token"); + await _client.StartAsync(); + + await Task.Delay(-1); + } - private Task Log(LogMessage message) - { - Console.WriteLine(message.ToString()); - return Task.CompletedTask; - } -} + private Task Log(LogMessage message) + { + Console.WriteLine(message.ToString()); + return Task.CompletedTask; + } +} \ No newline at end of file