Add Moodle Marketplace API documentation

.gitignore

@@ -7,6 +7,11 @@
 # Generated files
 .docusaurus
 .cache-loader
+# Marketplace OpenAPI spec fetched by scripts/marketplace-openapi.mjs and the reference
+# docusaurus-plugin-openapi-docs generates from it (see the `openapi` script in package.json)
+/.openapi
+/general/community/plugincontribution/marketplace-api/*
+!/general/community/plugincontribution/marketplace-api/_category_.yml
 
 # Misc
 .DS_Store

.markdownlint-cli2.cjs

@@ -266,6 +266,10 @@ config.renamedLinks = {
 
 module.exports = {
     config,
+    // Generated from the Marketplace OpenAPI spec at build time; not hand-written Markdown.
+    ignores: [
+        'general/community/plugincontribution/marketplace-api/**',
+    ],
     customRules: [
         path.join(__dirname, '.markdownlint/no-directional-quotation-marks'),
         path.join(__dirname, '.markdownlint/fix-migrated-links'),

docusaurus.config.js

@@ -89,7 +89,7 @@ const config = {
         },
     },
 
-    themes: ['@docusaurus/theme-mermaid'],
+    themes: ['@docusaurus/theme-mermaid', 'docusaurus-theme-openapi-docs'],
 
     presets: [
         [
@@ -167,6 +167,37 @@ const config = {
                 showLastUpdateTime: true,
                 remarkPlugins,
                 editCurrentVersion: true,
+                // The Marketplace API reference (see docusaurus-plugin-openapi-docs
+                // below) is generated into this instance, so it needs the ApiItem
+                // component from docusaurus-theme-openapi-docs to render its pages.
+                // ApiItem falls back to the regular DocItem for non-API docs.
+                docItemComponent: '@theme/ApiItem',
+            },
+        ],
+
+        // docusaurus-plugin-openapi-docs: generates reference docs for the Moodle
+        // Marketplace API from its OpenAPI spec, straight into the 'general' docs
+        // instance so they're picked up by the existing 'community' autogenerated
+        // sidebar like any other doc. The generated MDX relies on the components
+        // provided by docusaurus-theme-openapi-docs (registered in `themes`
+        // above), and the 'general' instance uses `docItemComponent:
+        // '@theme/ApiItem'` to render them.
+        // The spec is downloaded and prepared for the target environment by
+        // scripts/marketplace-openapi.mjs. Regenerate everything with: yarn openapi
+        [
+            'docusaurus-plugin-openapi-docs',
+            {
+                id: 'openapi',
+                docsPluginId: 'general',
+                config: {
+                    marketplace: {
+                        specPath: '.openapi/marketplace.json',
+                        outputDir: 'general/community/plugincontribution/marketplace-api',
+                        sidebarOptions: {
+                            groupPathsBy: 'tag',
+                        },
+                    },
+                },
             },
         ],
 

general/community/plugincontribution/marketplace-api/_category_.yml

@@ -0,0 +1,9 @@
+# The rest of this directory is generated from the Marketplace OpenAPI spec by
+# docusaurus-plugin-openapi-docs (see the `openapi` script in package.json) and is
+# git-ignored. This file is the only committed one: it turns the generated docs
+# into a single sidebar entry that opens the API introduction page.
+label: Moodle Marketplace API
+position: 2
+link:
+  type: doc
+  id: moodle-marketplace-api

general/community/plugincontribution/pluginsdirectory/api.md

@@ -9,7 +9,7 @@ tags:
 
 :::warning
 
-This page describes the Plugins Directory API, not [Moodle Marketplace APIs](general/community/plugincontribution/moodlemarketplaceapi.md).
+This page describes the Plugins Directory API, not the [Moodle Marketplace API](../marketplace-api/moodle-marketplace-api).
 
 For current Moodle Marketplace documentation, see [Moodle Marketplace documentation](https://moodle.atlassian.net/wiki/external/YTI4MmY4MWU2MDQyNDk5MTllZWY4YTBiNjA5ZDRjNWY).
 

package.json

@@ -5,13 +5,16 @@
   "scripts": {
     "docusaurus": "docusaurus",
     "start": "docusaurus start",
-    "build": "docusaurus build",
+    "build": "yarn openapi && docusaurus build",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy",
     "clear": "docusaurus clear",
     "serve": "docusaurus serve",
     "write-translations": "docusaurus write-translations",
     "write-heading-ids": "docusaurus write-heading-ids",
+    "openapi": "scripts/marketplace-openapi.mjs && docusaurus clean-api-docs all && docusaurus gen-api-docs all",
+    "gen-api-docs": "docusaurus gen-api-docs",
+    "clean-api-docs": "docusaurus clean-api-docs",
     "wikimedia-sync": "scripts/wikimedia-sync.js",
     "component-spellings": "scripts/component-helper.js spelling",
     "test": "jest",
@@ -45,6 +48,8 @@
     "acorn": "^8.11.3",
     "clsx": "^1.2.1",
     "commander": "5.1.0",
+    "docusaurus-plugin-openapi-docs": "^5.2.0",
+    "docusaurus-theme-openapi-docs": "^5.2.0",
     "dotenv": "^16.0.3",
     "hast-util-from-parse5": "^7.1.0",
     "libxmljs2": "^0.35.0",