docs: September 2019 Documentation Update (#1379)

* docs: adjust wording of ActivityType.Watching enum

Adjusts the xmldoc summary wording of the ActivityType.Watching enum to
fix a wording issue.

* Add D.NET Logo to Open Graph meta tags

* Update DescriptionGenerator
...And update color to suit the logo better

* Disable smooth scrolling due to user complaints

* Remove unnecessary spacing in sideaffix

* Update footer version

* Remove featherlight plugin

As it is unnecessary and can break image tags

* Adjust wordings regarding safe-handling of secrets

* Fix formatting for first bot token sample

* Add badges to homepage

* Minor wording fixes on terminal

* Update to higher quality PNG

* Add Discord.Net.Example in sln for build validation

* Clarify all instances of IAsnycEnumerable

* Clarify overridden props in SocketNewsChannel

* Add returns and params docs for SyncPermissionsAsync

* Remove/fix invalid XMLdoc strings

* Remove AppVeyor and add GitHub badge

Author: Still34

Discord.Net.sln

@@ -36,7 +36,9 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Discord.Net.Tests.Integrati
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Tests", "Tests", "{C7CF5621-7D36-433B-B337-5A2E3C101A71}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Discord.Net.Analyzers.Tests", "test\Discord.Net.Analyzers.Tests\Discord.Net.Analyzers.Tests.csproj", "{FC67057C-E92F-4E1C-98BE-46F839C8AD71}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Discord.Net.Analyzers.Tests", "test\Discord.Net.Analyzers.Tests\Discord.Net.Analyzers.Tests.csproj", "{FC67057C-E92F-4E1C-98BE-46F839C8AD71}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Discord.Net.Examples", "src\Discord.Net.Examples\Discord.Net.Examples.csproj", "{47820065-3CFB-401C-ACEA-862BD564A404}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
@@ -204,6 +206,18 @@ Global
 		{FC67057C-E92F-4E1C-98BE-46F839C8AD71}.Release|x64.Build.0 = Release|Any CPU
 		{FC67057C-E92F-4E1C-98BE-46F839C8AD71}.Release|x86.ActiveCfg = Release|Any CPU
 		{FC67057C-E92F-4E1C-98BE-46F839C8AD71}.Release|x86.Build.0 = Release|Any CPU
+		{47820065-3CFB-401C-ACEA-862BD564A404}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{47820065-3CFB-401C-ACEA-862BD564A404}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{47820065-3CFB-401C-ACEA-862BD564A404}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{47820065-3CFB-401C-ACEA-862BD564A404}.Debug|x64.Build.0 = Debug|Any CPU
+		{47820065-3CFB-401C-ACEA-862BD564A404}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{47820065-3CFB-401C-ACEA-862BD564A404}.Debug|x86.Build.0 = Debug|Any CPU
+		{47820065-3CFB-401C-ACEA-862BD564A404}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{47820065-3CFB-401C-ACEA-862BD564A404}.Release|Any CPU.Build.0 = Release|Any CPU
+		{47820065-3CFB-401C-ACEA-862BD564A404}.Release|x64.ActiveCfg = Release|Any CPU
+		{47820065-3CFB-401C-ACEA-862BD564A404}.Release|x64.Build.0 = Release|Any CPU
+		{47820065-3CFB-401C-ACEA-862BD564A404}.Release|x86.ActiveCfg = Release|Any CPU
+		{47820065-3CFB-401C-ACEA-862BD564A404}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -221,6 +235,7 @@ Global
 		{DBF8B16E-5967-4480-8EDE-15D98A0DF0C4} = {C7CF5621-7D36-433B-B337-5A2E3C101A71}
 		{E169E15A-E82C-45BF-8C24-C2CADB7093AA} = {C7CF5621-7D36-433B-B337-5A2E3C101A71}
 		{FC67057C-E92F-4E1C-98BE-46F839C8AD71} = {C7CF5621-7D36-433B-B337-5A2E3C101A71}
+		{47820065-3CFB-401C-ACEA-862BD564A404} = {BB59D5B5-E7B0-4BF4-8F82-D14431B2799B}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {D2404771-EEC8-45F2-9D71-F3373F6C1495}

docs/_template/description-generator/plugins/DocFX.Plugin.DescriptionGenerator.dll

@@ -5,9 +5,18 @@
   <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
   <title>{{#title}}{{title}}{{/title}}{{^title}}{{>partials/title}}{{/title}} {{#_appTitle}}| {{_appTitle}} {{/_appTitle}}</title>
   <meta name="viewport" content="width=device-width">
-  <meta name="title" content="{{#title}}{{title}}{{/title}}{{^title}}{{>partials/title}}{{/title}} {{#_appTitle}}| {{_appTitle}} {{/_appTitle}}">
+  <meta property="og:title" content="{{#title}}{{title}}{{/title}}{{^title}}{{>partials/title}}{{/title}} {{#_appTitle}}| {{_appTitle}} {{/_appTitle}}">
+  {{#_description}}<meta property="og:description" content="{{_description}}">{{/_description}}
+  <meta property="og:locale" content="en-us">
+  <meta property="og:type" content="website">
+  <meta property="og:site_name" content="Discord.Net Docs">
+  <meta property="og:image" content="https://cdn.jsdelivr.net/gh/discord-net/Discord.Net/docs/marketing/logo/PackageLogo.png">
+  <meta property="og:image:alt" content="Discord.Net Logo">
+  <meta name="theme-color" content="#995EA7"/>
   <meta name="generator" content="docfx {{_docfxVersion}}">
-  {{#_description}}<meta name="description" content="{{_description}}">{{/_description}}
+  <meta property="docfx:navrel" content="{{_navRel}}">
+  <meta property="docfx:tocrel" content="{{_tocRel}}">
+  <meta id="docfx-style:rel" content="{{_rel}}">
   <link rel="preload" href="{{_rel}}styles/search-worker.js" as="script">
   <link rel="preload" href="{{_rel}}fonts/glyphicons-halflings-regular.woff2" as="font" type="font/woff2" crossorigin="anonymous">
   <link rel="shortcut icon" href="{{_rel}}{{{_appFaviconPath}}}{{^_appFaviconPath}}favicon.ico{{/_appFaviconPath}}">
@@ -18,10 +27,6 @@
   <link rel="stylesheet" href="{{_rel}}styles/material.css">
   <link rel="stylesheet" href="{{_rel}}styles/theme-switcher.css">
   <link href="https://cdn.rawgit.com/noelboss/featherlight/1.7.6/release/featherlight.min.css" type="text/css" rel="stylesheet" />
-  <meta name="theme-color" content="#99AAB5"/>
-  <meta property="docfx:navrel" content="{{_navRel}}">
-  <meta property="docfx:tocrel" content="{{_tocRel}}">
-  <meta id="docfx-style:rel" content="{{_rel}}">
   {{#_noindex}}<meta name="searchOption" content="noindex">{{/_noindex}}
   {{#_enableSearch}}<meta property="docfx:rel" content="{{_rel}}">{{/_enableSearch}}
   {{#_enableNewTab}}<meta property="docfx:newtab" content="true">{{/_enableNewTab}}

docs/_template/light-dark-theme/partials/head.tmpl.partial

@@ -3,8 +3,6 @@
 <script type="text/javascript" src="{{_rel}}styles/docfx.vendor.js"></script>
 <script type="text/javascript" src="{{_rel}}styles/docfx.js"></script>
 <script type="text/javascript" src="{{_rel}}styles/main.js"></script>
-<script type="text/javascript" src="https://cdn.rawgit.com/noelboss/featherlight/master/release/featherlight.min.js" charset="utf-8"></script>
-<script type="text/javascript" src="{{_rel}}styles/plugin-featherlight.js"></script>
 <script type="text/javascript" src="{{_rel}}styles/styleswitcher.js"></script>
 <script type="text/javascript" src="https://malsup.github.io/jquery.corner.js"></script>
 <script type="text/javascript" src="{{_rel}}styles/cornerify.js"></script>

docs/_template/light-dark-theme/partials/scripts.tmpl.partial

@@ -6,7 +6,6 @@ body {
     font-display: optional;
     height: 100%;
     font-size: 15px;
-    scroll-behavior: smooth;
 }
 
 code{
@@ -92,6 +91,10 @@ article.content h6{
     line-height: 140%;
 }
 
+.sideaffix > div.contribution {
+    margin-bottom: 0;
+}
+
 header .navbar {
     border-width: 0 0 0px;
     border-radius: 0;

docs/_template/light-dark-theme/styles/master.css

@@ -35,7 +35,8 @@
         "**/images/**",
         "**/samples/**",
         "langwordMapping.yml",
-        "marketing/logo/SVG/**.svg",
+        "marketing/logo/**.svg",
+        "marketing/logo/**.png",
         "favicon.ico"
       ]
     }],
@@ -50,7 +51,7 @@
     "overwrite": "_overwrites/**/**.md",
     "globalMetadata": {
       "_appTitle": "Discord.Net Documentation",
-      "_appFooter": "Discord.Net (c) 2015-2019 2.0.1",
+      "_appFooter": "Discord.Net (c) 2015-2019 2.1.1",
       "_enableSearch": true,
       "_appLogoPath": "marketing/logo/SVG/Logomark Purple.svg",
       "_appFaviconPath":  "favicon.ico"

docs/_template/light-dark-theme/styles/plugin-featherlight.js

@@ -146,23 +146,6 @@ method with the application's "token."
 > Pay attention to what you are copying from the developer portal!
 > A token is not the same as the application's "client secret."
 
-> [!IMPORTANT]
-> Your bot's token can be used to gain total access to your bot, so
-> **do not** share this token with anyone else! You should store this
-> token in an external source if you plan on distributing
-> the source code for your bot.
->
-> In the following example, we retrieve the token from the environment
-> variable `DiscordToken`. Please note that this is *not* designed to
-> be used in a production environment, as the secrets are stored in
-> plain-text.
->
-> For information on how to set an environment variable, please see
-> instructions below,
->
-> * Windows: [How to Create Environment Variables Shortcut in Windows](https://www.tenforums.com/tutorials/121742-create-environment-variables-shortcut-windows.html)
-> * Linux: [How To Read and Set Environmental and Shell Variables on a Linux VPS](https://www.digitalocean.com/community/tutorials/how-to-read-and-set-environmental-and-shell-variables-on-a-linux-vps)
-> * macOS: [How do I set environment variables on OS X?](https://apple.stackexchange.com/questions/106778/how-do-i-set-environment-variables-on-os-x)
 
 We may now invoke the client's [StartAsync] method, which will
 start connection/reconnection logic. It is important to note that
@@ -175,6 +158,22 @@ Finally, we will want to block the async main method from returning
 when running the application. To do this, we can await an infinite delay
 or any other blocking method, such as reading from the console.
 
+> [!IMPORTANT]
+> Your bot's token can be used to gain total access to your bot, so
+> **do not** share this token with anyone else! You should store this
+> token in an external source if you plan on distributing
+> the source code for your bot.
+>
+> In the following example, we retrieve the token from a pre-defined
+> variable, which is **NOT** secure, especially if you plan on 
+> distributing the application in any shape or form.
+>
+> We recommend alternative storage such as 
+> [Environment Variables], an external configuration file, or a 
+> secrets manager for safe-handling of secrets.
+>
+> [Environment Variables]: https://en.wikipedia.org/wiki/Environment_variable
+
 The following lines can now be added:
 
 [!code-csharp[Create client](samples/first-bot/client.cs)]

docs/docfx.json

@@ -78,7 +78,7 @@ published to our [MyGet feed]. See
 
 ### [Using dotnet CLI](#tab/dotnet-cli)
 
-1. Launch your terminal
+1. Launch a terminal of your choice
 2. Navigate to where your `*.csproj` is located
 3. Enter `dotnet add package Discord.Net`
 
@@ -90,7 +90,7 @@ In order to compile Discord.Net, you will need the following:
 
 ### Using Visual Studio
 
-* [Visual Studio 2017](https://www.visualstudio.com/)
+* [Visual Studio 2019](https://visualstudio.microsoft.com/)
 * [.NET Core SDK]
 
 The .NET Core and Docker workload is required during Visual Studio
@@ -109,7 +109,7 @@ When running any Discord.Net-powered bot on an older operating system
 you may encounter a @System.PlatformNotSupportedException upon
 connecting.
 
-You may resolve this by either targeting .NET Core 2.1 or later, or
+You may resolve this by either targeting .NET Core 2.1 or higher, or
 by installing one or more custom packages as listed below.
 
 #### [Targeting .NET Core 2.1](#tab/core2-1)
@@ -141,4 +141,4 @@ over the default ones.
 
 ***
 
-[.NET Core SDK]: https://www.microsoft.com/net/download/
+[.NET Core SDK]: https://dotnet.microsoft.com/download

docs/guides/getting_started/first-bot.md

@@ -53,7 +53,7 @@ adding the feed to your package source.
 
 ### [Using dotnet CLI](#tab/cli)
 
-1. Launch your terminal
+1. Launch a terminal of your choice
 2. Navigate to where your `*.csproj` is located
 3. Type `dotnet add package Discord.Net --source https://www.myget.org/F/discord-net/api/v3/index.json`