`build-storybook --docs` has no effect

Describe the bug

The --docs flag to the build-storybook CLI has no discernible effect (see docs). The flag (when combined with --no-manager-cache) does work with start-storybook. Confirmed on 6.3.7 and 6.4.0-alpha.32.

To Reproduce

Repro repo: https://github.com/kylegach/build-storybook-docs-mode

_I also published the build result to GH Pages: https://kylegach.github.io/build-storybook-docs-mode/_

1. Add "build-storybook:docs": "build-storybook -s public -o docs --docs" to package.json’s "scripts"
2. (Literally no other changes)
3. Run yarn build-storybook:docs
4. Confirm that the result is the same as yarn build-storybook

System

Environment Info

System:
    OS: macOS Mojave 10.14.6
    CPU: (12) x64 Intel(R) Core(TM) i7-8850H CPU @ 2.60GHz
  Binaries:
    Node: 14.16.0 - ~/.nvm/versions/node/v14.16.0/bin/node
    Yarn: 3.0.1 - ~/.yarn/bin/yarn
    npm: 6.14.11 - ~/.nvm/versions/node/v14.16.0/bin/npm
  Browsers:
    Chrome: 89.0.4389.128
    Firefox: 88.0.1
    Safari: 14.1.1
  npmPackages:
    @storybook/addon-actions: ^6.4.0-alpha.32 => 6.4.0-alpha.32
    @storybook/addon-docs: ^6.4.0-alpha.32 => 6.4.0-alpha.32
    @storybook/addon-essentials: ^6.4.0-alpha.32 => 6.4.0-alpha.32
    @storybook/addon-links: ^6.4.0-alpha.32 => 6.4.0-alpha.32
    @storybook/node-logger: ^6.4.0-alpha.32 => 6.4.0-alpha.32
    @storybook/preset-create-react-app: ^3.2.0 => 3.2.0
    @storybook/react: ^6.4.0-alpha.32 => 6.4.0-alpha.32

Additional context

npx sb@next repro

✔ 🌈 Select the repro framework › react
✔ 📝 Select the repro base template › cra
✔ Enter the output directory … build-storybook-docs-mode
🏃 Running cra into /Users/kg666261/projects/build-storybook-docs-mode

🏃 Starting for cra latest

{
  name: 'cra',
  version: 'latest',
  appName: 'build-storybook-docs-mode',
  creationPath: '/Users/kg666261/projects',
  cwd: '/Users/kg666261/projects/build-storybook-docs-mode',
  e2e: false,
  pnp: false,
  framework: 'react',
  generator: 'npx create-react-app@{{version}} {{appName}} --use-npm && cd {{appName}} && echo "FAST_REFRESH=true" > .env && echo "SKIP_PREFLIGHT_CHECK=true" > .env'
}

[shilman]

Ta-da!! I just released https://github.com/storybookjs/storybook/releases/tag/v6.4.14 containing PR #17300 that references this issue. Upgrade today to the @latest NPM tag to try it out!

npx sb upgrade

[shilman]

@kylemh Strangely, when I tried it again today it reproduces per your instructions 🤔

I’ve isolated the bug and am looking for a fix. It was nondeterministic because it involves caching. Specifically, we cache the manager UI when we ship Storybook. If your main.js configuration matches the default configuration, it uses the cached build, which doesn’t have DOCS_MODE set. The dev server has a --no-manager-cache flag, but the production build does not.

Therefore we can either:

• Incorporate --docs into the cache busting behavior
• Add --no-manager-cache to build-storybook
• Always build the manager in production (adding ~10s to the build time)

I’m tempted to go with the last option for simplicity’s sake