Improve new docs site. (#2843)

* Improve parameter padding and add discord link.

* Update xref service for docs.

Reason: https://github.com/dotnet/docfx/issues/9659

* Update docs readme to specify docfx version.

* Update to latest DocFX.

* update action & add manual trigger

.github/workflows/docs.yml

@@ -4,6 +4,7 @@ on:
   push:
     tags:
       - '*'
+  workflow_dispatch:
       
 jobs:
   build:
@@ -18,7 +19,7 @@ jobs:
         dotnet-version: 8.0.x
 
     - name: Setup DocFX
-      run: dotnet tool install -g docfx --version 2.71.0
+      run: dotnet tool install -g docfx --version 2.75.2
 
     - name: Build DNet docs
       run: docfx docs/docfx.json

docs/README.md

@@ -3,13 +3,15 @@
 The documentation for the Discord.Net library uses [DocFX][docfx-main].
 Instructions for installing this tool can be found [here][docfx-installing].
 
+> [!IMPORTANT]
+> You must use DocFX version **2.75.2** for everything to work.
+
 1. Navigate to the root of the repository.
 2. Build the docs using `docfx docs/docfx.json`. Add the `--serve`
- parameter to preview the site locally. Some elements of the page
- may appear incorrectly when hosted offline.
+ parameter to preview the site locally.
 
 Please note that if you intend to target a specific version, ensure
 that you have the correct version checked out.
 
 [docfx-main]: https://dotnet.github.io/docfx/
-[docfx-installing]: https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html
+[docfx-installing]: https://dotnet.github.io/docfx/index.html

docs/_template/material/public/main.css

@@ -183,12 +183,17 @@ code {
   box-shadow: var(--card-box-shadow);
 }
 
-/* MAKES DERIVED LIST READABLE */
-:is(dl.typelist.derived, dl.typelist.extensionMethods) > dd > div::after {
+/* MAKES PARAMETERS MORE SPACIOUS */
+dl.parameters > dt > code {
+    padding: 3px;
+}
+
+/* MAKES INHERITANCE LIST READABLE */
+:is(dl.typelist.inheritedMembers, dl.typelist.extensionMethods) > dd > div::after {
   content: none !important;
 }
 
-:is(dl.typelist.derived, dl.typelist.extensionMethods) > dd > div {
+:is(dl.typelist.inheritedMembers, dl.typelist.extensionMethods) > dd > div {
   display: block !important;
 }
 
@@ -212,7 +217,7 @@ article[data-uid="Root.Landing"] img[alt="logo"] {
 }
 
 /* MAKES SIDEBAR LINKS A BIT MORE DISTINGUISHABLE */
-.affix ul li a {
+.affix ul li a:not(.link-body-emphasis) {
   display: block !important;
   margin-left: 8px !important;
 }

docs/_template/material/public/main.js

@@ -4,6 +4,11 @@
             icon: 'github',
             href: 'https://github.com/discord-net/Discord.Net',
             title: 'GitHub'
+        },
+        {
+            icon: 'discord',
+            href: 'https://discord.gg/dnet',
+            title: 'Discord'
         }
     ]
 }

docs/docfx.json

@@ -53,7 +53,7 @@
     ],
     "postProcessors": [
       "ExtractSearchIndex",
-      "DescriptionPostProcessor"	  
+      "DescriptionPostProcessor"
     ],
     "overwrite": "_overwrites/**/**.md",
     "globalMetadata": {
@@ -63,6 +63,6 @@
       "_appLogoPath": "marketing/logo/SVG/Logomark Purple.svg",
       "_appFaviconPath": "favicon.ico"
     },
-    "xrefService": ["https://learn.microsoft.com/api/xref/query?uid={uid}"]
+    "xref": ["https://github.com/dotnet/docfx/raw/main/.xrefmap.json"]
   }
 }