Merge pull request #19713 from storybookjs/tom/sb-895-docs-option-to-turn-on-docs-page

Allow setting docsPage `automatic` to create docs entries for all components

code/lib/cli/src/automigrate/fixes/docsPage-automatic.ts

@@ -0,0 +1,61 @@
+import chalk from 'chalk';
+import { dedent } from 'ts-dedent';
+
+import type { ConfigFile } from '@storybook/csf-tools';
+import { readConfig, writeConfig } from '@storybook/csf-tools';
+import { getStorybookInfo } from '@storybook/core-common';
+
+import type { Fix } from '../types';
+
+const logger = console;
+
+interface DocsPageAutomaticFrameworkRunOptions {
+  main: ConfigFile;
+}
+
+/**
+ * Set the docs.docsPage option to automatic if it isn't already set
+ */
+export const docsPageAutomatic: Fix<DocsPageAutomaticFrameworkRunOptions> = {
+  id: 'docsPageAutomatic',
+
+  async check({ packageManager }) {
+    const packageJson = packageManager.retrievePackageJson();
+
+    const { mainConfig } = getStorybookInfo(packageJson);
+
+    if (!mainConfig) {
+      logger.warn('Unable to find storybook main.js config, skipping');
+      return null;
+    }
+
+    const main = await readConfig(mainConfig);
+    const docs = main.getFieldValue(['docs']);
+
+    return docs?.docsPage === undefined ? { main } : null;
+  },
+
+  prompt() {
+    const docsPageAutomaticFormatted = chalk.cyan(`docs: { docsPage: 'automatic' }`);
+
+    return dedent`
+      We've detected that your main.js configuration file has not configured docsPage. In 6.x we
+      we defaulted to having a docsPage for every story, in 7.x you need to opt in per-component.
+      However, we can set the \`docs.docsPage\` to 'automatic' to approximate the old behaviour:
+
+      ${docsPageAutomaticFormatted}
+
+      More info: ${chalk.yellow(
+        'https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#docs-page'
+      )}
+    `;
+  },
+
+  async run({ result: { main }, dryRun }) {
+    logger.info(`✅ Setting 'docs.docsPage' to 'automatic' in main.js`);
+    if (!dryRun) {
+      main.setFieldValue(['docsPage', 'docs'], 'automatic');
+      await writeConfig(main);
+    }
+  },
+};

code/lib/cli/src/automigrate/fixes/index.ts

@@ -12,6 +12,7 @@ import { sbScripts } from './sb-scripts';
 import { newFrameworks } from './new-frameworks';
 import { removedGlobalClientAPIs } from './remove-global-client-apis';
 import { mdx1to2 } from './mdx-1-to-2';
+import { docsPageAutomatic } from './docsPage-automatic';
 
 export * from '../types';
 
@@ -28,4 +29,5 @@ export const fixes: Fix[] = [
   newFrameworks,
   removedGlobalClientAPIs,
   mdx1to2,
+  docsPageAutomatic,
 ];

code/lib/client-api/src/StoryStoreFacade.ts

@@ -191,12 +191,12 @@ export class StoryStoreFacade<TFramework extends AnyFramework> {
 
     // NOTE: this logic is equivalent to the `extractStories` function of `StoryIndexGenerator`
     const docsOptions = (global.DOCS_OPTIONS || {}) as DocsOptions;
+    const docsPageOptedIn =
+      docsOptions.docsPage === 'automatic' ||
+      (docsOptions.docsPage && componentTags.includes('docsPage'));
     if (docsOptions.enabled && storyExports.length) {
       // We will use tags soon and this crappy filename test will go away
-      if (
-        fileName.match(/\.mdx$/) ||
-        (docsOptions.docsPage && componentTags.includes('docsPage'))
-      ) {
+      if (fileName.match(/\.mdx$/) || docsPageOptedIn) {
         const name = docsOptions.defaultName;
         const docsId = toId(componentId || title, name);
         this.entries[docsId] = {

code/lib/core-client/src/start.test.ts

@@ -1295,6 +1295,50 @@ describe('start', () => {
         `);
       });
     });
+    describe('when docsOptions.docsPage = automatic', () => {
+      beforeEach(() => {
+        global.DOCS_OPTIONS = { enabled: true, docsPage: 'automatic', defaultName: 'Docs' };
+      });
+
+      it('adds stories for each component with docsPage tag', async () => {
+        const renderToDOM = jest.fn();
+
+        const { configure, clientApi } = start(renderToDOM);
+        configure('test', () => {
+          (clientApi as any).addParameters({
+            docs: { renderer: () => ({ render: jest.fn((_, _2, _3, d) => d()) }) },
+          });
+          clientApi
+            .storiesOf('Component A', { id: 'file1' } as NodeModule)
+            .add('Story One', jest.fn())
+            .add('Story Two', jest.fn());
+
+          clientApi
+            .storiesOf('Component B', { id: 'file2' } as NodeModule)
+            .addParameters({ tags: ['docsPage'] })
+            .add('Story Three', jest.fn());
+
+          return [componentCExports];
+        });
+
+        await waitForRender();
+        const setIndexData = mockChannel.emit.mock.calls.find(
+          (call: [string, any]) => call[0] === SET_INDEX
+        )[1];
+        expect(Object.keys(setIndexData.entries)).toMatchInlineSnapshot(`
+          Array [
+            "component-a--docs",
+            "component-a--story-one",
+            "component-a--story-two",
+            "component-b--docs",
+            "component-b--story-three",
+            "component-c--docs",
+            "component-c--story-one",
+            "component-c--story-two",
+          ]
+        `);
+      });
+    });
   });
 
   describe('auto-title', () => {

code/lib/core-server/src/utils/StoryIndexGenerator.test.ts

@@ -441,6 +441,39 @@ describe('StoryIndexGenerator', () => {
         `);
       });
 
+      it('generates an entry for every CSF file when docsOptions.docsPage = automatic', async () => {
+        const specifier: CoreCommon_NormalizedStoriesSpecifier = normalizeStoriesEntry(
+          './src/**/*.stories.(ts|js|jsx)',
+          options
+        );
+
+        const generator = new StoryIndexGenerator([specifier], {
+          ...docsPageOptions,
+          docs: {
+            ...docsPageOptions.docs,
+            docsPage: 'automatic',
+          },
+        });
+        await generator.initialize();
+
+        expect(Object.keys((await generator.getIndex()).entries)).toMatchInlineSnapshot(`
+          Array [
+            "a--docs",
+            "a--story-one",
+            "b--docs",
+            "b--story-one",
+            "d--docs",
+            "d--story-one",
+            "first-nested-deeply-f--docs",
+            "first-nested-deeply-f--story-one",
+            "nested-button--docs",
+            "nested-button--story-one",
+            "second-nested-g--docs",
+            "second-nested-g--story-one",
+          ]
+        `);
+      });
+
       it('does not generate a docs page entry if there is a standalone entry with the same name', async () => {
         const csfSpecifier: CoreCommon_NormalizedStoriesSpecifier = normalizeStoriesEntry(
           './src/A.stories.js',

code/lib/core-server/src/utils/StoryIndexGenerator.ts

@@ -224,12 +224,12 @@ export class StoryIndexGenerator {
       });
 
       if (this.options.docs.enabled && csf.stories.length) {
+        const { docsPage } = this.options.docs;
+        const docsPageOptedIn =
+          docsPage === 'automatic' || (docsPage && componentTags.includes('docsPage'));
         // We always add a template for *.stories.mdx, but only if docs page is enabled for
         // regular CSF files
-        if (
-          storyIndexer.addDocsTemplate ||
-          (this.options.docs.docsPage && componentTags.includes('docsPage'))
-        ) {
+        if (storyIndexer.addDocsTemplate || docsPageOptedIn) {
           const name = this.options.docs.defaultName;
           const id = toId(csf.meta.title, name);
           entries.unshift({

code/lib/types/src/modules/core-common.ts

@@ -296,9 +296,10 @@ export type DocsOptions = {
    */
   defaultName?: string;
   /**
-   * Should we generate a docs entry per CSF file?
+   * Should we generate a docs entry per CSF file with the `docsPage` tag?
+   * Set to 'automatic' to generate an entry irrespective of tag.
    */
-  docsPage?: boolean;
+  docsPage?: boolean | 'automatic';
   /**
    * Only show doc entries in the side bar (usually set with the `--docs` CLI flag)
    */