website: add "API Reference" generation

.config/dotnet-tools.json

@@ -6,7 +6,15 @@
       "version": "5.1.250801",
       "commands": [
         "dotnet-format"
-      ]
+      ],
+      "rollForward": false
+    },
+    "docfx": {
+      "version": "2.78.2",
+      "commands": [
+        "docfx"
+      ],
+      "rollForward": false
     }
   }
 }

.github/workflows/deploy-website.yml

@@ -4,6 +4,7 @@ on:
   push:
     paths:
       - 'docs/**'
+      - 'Consul/**'
   pull_request:
     paths:
       - 'docs/**'
@@ -77,6 +78,16 @@ jobs:
         run: yarn install
         working-directory: ./docs
 
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+
+      - name: Restore tool
+        run: dotnet tool restore
+
+      - name: Generate API reference using DocFX
+        run: yarn run api:generate
+        working-directory: ./docs
+
       - name: Build
         run: yarn run build
         working-directory: ./docs

docs/README.md

@@ -20,6 +20,28 @@ yarn start
 This command starts a local development server and opens up a browser window. Most changes are reflected live without
 having to restart the server.
 
+### Generating the "API Reference" section
+
+You can generate an API Reference section automatically based on the source code
+using [DocFX](https://dotnet.github.io/docfx/) by running the following commands:
+
+```shell
+# restore the DocFX tool
+dotnet tool restore
+
+# generate markdown files using DocFX
+yarn run generate-api-folder
+
+# transform the generated markdown files
+yarn run transform-api-folder
+
+# or using one command that does both
+yarn run api:generate
+
+# to clean the generated files
+yarn run api:clean
+```
+
 ## Build
 
 ```shell

docs/docfx.json

@@ -0,0 +1,17 @@
+{
+  "metadata": [
+    {
+      "src": [
+        {
+          "src": "../Consul",
+          "files": [
+            "**/*.csproj"
+          ]
+        }
+      ],
+      "dest": "api",
+      "output": ".",
+      "outputFormat": "markdown"
+    }
+  ]
+}

docs/docusaurus.config.js

@@ -1,6 +1,7 @@
 // @ts-check
 // Note: type annotations allow type checking and IDEs autocompletion
 
+const fs = require('node:fs');
 const lightCodeTheme = require('prism-react-renderer/themes/github');
 const darkCodeTheme = require('prism-react-renderer/themes/dracula');
 
@@ -12,6 +13,7 @@ const consulDotNetVersion = clean_version(process.env.CONSUL_DOT_NET_VERSION ||
 const consulAPIVersion = clean_version(extract_consul_version(consulDotNetVersion));
 const url = process.env.URL || `https://consuldot.net`;
 const baseUrl = process.env.BASE_URL || `/`;
+const shouldIncludeApiReference = fs.existsSync('./api');
 
 function clean_version(version) {
     if (version) {
@@ -83,6 +85,18 @@ const config = {
         ],
     ],
 
+    plugins: [
+        shouldIncludeApiReference && [
+            '@docusaurus/plugin-content-docs',
+            {
+                id: 'api',
+                path: 'api',
+                routeBasePath: 'api',
+                sidebarPath: require.resolve('./sidebars.js'),
+            },
+        ],
+    ],
+
     themeConfig:
     /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
         ({
@@ -101,6 +115,13 @@ const config = {
                         label: 'Docs',
                         position: 'left',
                     },
+                    shouldIncludeApiReference && {
+                        docsPluginId: 'api',
+                        docId: 'Consul/README',
+                        type: 'doc',
+                        label: 'API Reference',
+                        position: 'left',
+                    },
                     {
                         to: '/docs/category/contributing',
                         label: 'Contribute',
@@ -126,7 +147,7 @@ const config = {
                         className: 'header-twitter-link',
                         'aria-label': 'Twitter',
                     },
-                ],
+                ].filter(Boolean),
             },
             footer: {
                 links: [

docs/package.json

@@ -13,6 +13,10 @@
     "serve": "docusaurus serve",
     "write-translations": "docusaurus write-translations",
     "write-heading-ids": "docusaurus write-heading-ids",
+    "generate-api-folder": "dotnet tool run docfx metadata docfx.json",
+    "transform-api-folder": "node src/scripts/transformApiFolder.js --path=api",
+    "api:generate": "yarn generate-api-folder && yarn transform-api-folder",
+    "api:clean": "rimraf api",
     "typecheck": "tsc"
   },
   "dependencies": {
@@ -28,6 +32,7 @@
     "@docusaurus/module-type-aliases": "^2.3.1",
     "@tsconfig/docusaurus": "^1.0.5",
     "dotenv": "^16.0.3",
+    "js-yaml": "^4.1.0",
     "typescript": "^4.7.4"
   },
   "browserslist": {