feat(@lexical/website): Packages documentation automatic generation (#…

…5965)

packages/lexical-list/README.md

@@ -1,4 +1,4 @@
-`@lexical/list`
+# `@lexical/list`
 
 [![See API Documentation](https://lexical.dev/img/see-api-documentation.svg)](https://lexical.dev/docs/api/modules/lexical_list)
 

packages/lexical-website/.gitignore

@@ -8,6 +8,7 @@
 .docusaurus
 .cache-loader
 /docs/api
+/docs/packages
 
 # Misc
 .DS_Store

packages/lexical-website/docusaurus.config.js

@@ -207,6 +207,21 @@ const config = {
   onBrokenMarkdownLinks: 'throw',
   organizationName: 'facebook',
   plugins: [
+    [
+      './plugins/package-docs',
+      /** @type {import('./plugins/package-docs').PackageDocsPluginOptions} */
+      {
+        baseDir: path.resolve(__dirname, '..'),
+        editUrl: `${GITHUB_REPO_URL}/tree/main/packages/`,
+        packageFrontMatter: {
+          lexical: [
+            'sidebar_position: 1',
+            'sidebar_label: lexical (core)',
+          ].join('\n'),
+        },
+        targetDir: path.resolve(__dirname, 'docs/packages'),
+      },
+    ],
     './plugins/webpack-buffer',
     ['docusaurus-plugin-typedoc', docusaurusPluginTypedocConfig],
     async function tailwindcss() {

packages/lexical-website/plugins/package-docs/index.js

@@ -0,0 +1,79 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const glob = require('glob');
+// Not using packagesManager since it will cache package.json files
+const {PackageMetadata} = require('../../../../scripts/shared/PackageMetadata');
+
+/**
+ * @typedef {Object} PackageDocsPluginOptions
+ * @property {string} baseDir
+ * @property {editUrl} editUrl
+ * @property {string} targetDir
+ * @property {Record<string, string>} packageFrontMatter
+ */
+
+/**
+ * Watch all public monorepo packages/{project}/README.md files and
+ * copy them to docs/packages/{project}.md
+ *
+ * @param {import('@docusaurus/types').LoadContext} context
+ * @param {PackageDocsPluginOptions} options
+ * @returns {import('@docusaurus/types').Plugin}
+ */
+module.exports = async function (context, options) {
+  return {
+    getPathsToWatch: () => [`${options.baseDir}/*/{README.md,package.json}`],
+    loadContent: () => {
+      fs.mkdirSync(options.targetDir, {recursive: true});
+      const oldTargets = new Set(
+        glob.sync(path.resolve(options.targetDir, '*.md')),
+      );
+      for (const srcPath of glob.sync(`${options.baseDir}/*/README.md`)) {
+        const jsonPath = path.resolve(path.dirname(srcPath), 'package.json');
+        if (!fs.existsSync(jsonPath)) {
+          continue;
+        }
+        const metadata = new PackageMetadata(jsonPath);
+        if (metadata.isPrivate()) {
+          continue;
+        }
+        const folderName = metadata.getDirectoryName();
+        const targetPath = path.resolve(options.targetDir, `${folderName}.md`);
+        /** @type {string|undefined} */
+        const frontMatter = [
+          `# Do not edit! Generated from ${path.relative(
+            path.dirname(targetPath),
+            srcPath,
+          )}`,
+          options.packageFrontMatter[folderName],
+          `custom_edit_url: ${options.editUrl.replace(
+            /\/$/,
+            '',
+          )}/${folderName}/README.md`,
+        ]
+          .filter(Boolean)
+          .map((s) => s.trim())
+          .join('\n');
+        fs.writeFileSync(
+          targetPath,
+          `---\n${frontMatter}\n---\n\n${fs.readFileSync(srcPath, 'utf-8')}`,
+        );
+        oldTargets.delete(targetPath);
+      }
+      for (const oldPath of oldTargets) {
+        fs.unlinkSync(oldPath);
+      }
+    },
+    name: 'package-docs',
+  };
+};

scripts/__tests__/unit/build.test.js

@@ -93,25 +93,20 @@ describe('public package.json audits (`npm run update-packages` to fix most issu
 });
 
 describe('documentation audits (`npm run update-packages` to fix most issues)', () => {
-  const webPkg = packagesManager.getPackageByDirectoryName('lexical-website');
   packagesManager.getPublicPackages().forEach((pkg) => {
     const npmName = pkg.getNpmName();
     describe(npmName, () => {
       const root = pkg.resolve('..', '..');
-      [
-        pkg.resolve('README.md'),
-        webPkg.resolve('docs', 'packages', `${pkg.getDirectoryName()}.md`),
-      ].forEach((docPath) => {
-        describe(path.relative(root, docPath), () => {
-          it('exists', () => expect(fs.existsSync(docPath)).toBe(true));
-          if (path.basename(docPath) === 'README.md') {
-            it('does not have the TODO description', () => {
-              expect(fs.readFileSync(docPath, 'utf8')).not.toContain(
-                'TODO: This package needs a description!',
-              );
-            });
-          }
-        });
+      const docPath = pkg.resolve('README.md');
+      describe(path.relative(root, docPath), () => {
+        it('exists', () => expect(fs.existsSync(docPath)).toBe(true));
+        if (path.basename(docPath) === 'README.md') {
+          it('does not have the TODO description', () => {
+            expect(fs.readFileSync(docPath, 'utf8')).not.toContain(
+              'TODO: This package needs a description!',
+            );
+          });
+        }
       });
     });
   });

scripts/create-docs.js

@@ -12,21 +12,6 @@ const fs = require('fs-extra');
 const path = require('node:path');
 const {packagesManager} = require('./shared/packagesManager');
 
-const webPkg = packagesManager.getPackageByDirectoryName('lexical-website');
-
-function sidebarTemplate(npmName, readmePath) {
-  return (
-    `
----
-title: ''
-sidebar_label: '${npmName}'
----
-
-{@import ${readmePath}}
-`.trim() + '\n'
-  );
-}
-
 function readmeTemplate(npmName, directoryName, description) {
   const apiModuleName = directoryName.replace(/-/g, '_');
   return (
@@ -40,17 +25,12 @@ ${description}
   );
 }
 
-function updateDocs() {
+function createDocs() {
   packagesManager.getPublicPackages().forEach((pkg) => {
     const npmName = pkg.getNpmName();
     const directoryName = pkg.getDirectoryName();
     const root = pkg.resolve('..', '..');
     const readmePath = pkg.resolve('README.md');
-    const sidebarPath = webPkg.resolve(
-      'docs',
-      'packages',
-      `${directoryName}.md`,
-    );
     if (!fs.existsSync(readmePath)) {
       console.log(`Creating ${path.relative(root, readmePath)}`);
       fs.writeFileSync(
@@ -63,17 +43,7 @@ function updateDocs() {
         ),
       );
     }
-    if (!fs.existsSync(sidebarPath)) {
-      console.log(`Creating ${path.relative(root, sidebarPath)}`);
-      fs.writeFileSync(
-        sidebarPath,
-        sidebarTemplate(
-          npmName,
-          path.relative(path.dirname(sidebarPath), readmePath),
-        ),
-      );
-    }
   });
 }
 
-updateDocs();
+createDocs();