bug(cdk/scrolling): Documentation for using cdk-virtual-scroll-viewport is incorrect

[howardjing]

Reproduction

The API reference for Angular CDK scrolling (https://material.angular.io/cdk/scrolling/api) only mentions CdkScrollableModule and does not mention ScrollingModule. ScrollingModule should be mentioned in the documentation -- for example it is required to use cdk-virtual-scroll-viewport.

From the documentation:

API reference for Angular CDK scrolling
import {CdkScrollableModule} from '@angular/cdk/scrolling';

In order to use cdk-virtual-scroll-viewport, I need to import ScrollingModule from @angular/cdk/scrolling instead.

Steps to reproduce:

1. Go to the following StackBlitz: https://stackblitz.com/edit/angular-ivy-xt5sg3?file=src%2Fapp%2Fapp.module.ts. You will see the following error:

   Error in src/app/app.component.html (2:1)
   'cdk-virtual-scroll-viewport' is not a known element:
   1. If 'cdk-virtual-scroll-viewport' is an Angular component, then verify that it is part of this module.
   2. If 'cdk-virtual-scroll-viewport' is a Web Component then add 'CUSTOM_ELEMENTS_SCHEMA' to the 
   '@NgModule.schemas' of this component to suppress this message.
   

2. Import ScrollingModule and it will work again.

Expected Behavior

I expect the documentation at https://material.angular.io/cdk/scrolling/api to mention ScrollingModule, something along the lines of

API reference for Angular CDK scrolling

/**
 * To use the following:
 * - CdkScrollable
 */
import {CdkScrollableModule} from '@angular/cdk/scrolling';

/**
 * To use the following:
 *  - CdkFixedSizeVirtualScroll
 *  - CdkVirtualForOf
 *  - CdkVirtualScrollViewport
 */
import {ScrollingModule} from '@angular/cdk/scrolling';

Actual Behavior

The documentation does not mention ScrollingModule

[AbhignAB149]

Yeah I also encountered this issue when i followed documentation ,which popped with error cdk scrolling module is not compatible with ivy compiler ... After trying with different possibilities, scrolling module actually worked

[howardjing]

@jelbourn I poked around to see what it would take to update the docs and made this commit: howardjing@ae20157

However, I have no idea how to test it (i.e. I don't how to generate the docs). These files seem relevant, but it's not obvious to me how to actually run the command to see what the output is / if my PR actually does anything:

• I assume this is where the import gets generated:

  components/tools/dgeni/templates/entry-point.template.html

  Line 41 in a295ed0

  import {{$ doc.primaryExportName $}} from '{$ doc.moduleImportPath $}';

• This seems like a relevant decorator:

  components/tools/dgeni/common/decorators.ts

  Lines 46 to 49 in a295ed0

  	export function isPrimaryExportDoc(doc: any) {
  	return (doc.tags && doc.tags.tags || [])
  	.some((tag: any) => tag.tagName === 'docs-primary-export');
  	}

• This seems to be where I can generate docs:

  components/src/BUILD.bazel

  Lines 28 to 29 in a295ed0

  	dgeni_api_docs(
  	name = "api-docs",

I tried running the following command in my locally cloned angular/components folder:

❯ yarn run bazel run src:api-docs

But I get the following error:

ERROR: Cannot run target //src:api-docs: Not executable

What am I overlooking to generate the docs?

[jelbourn]

Yeah, it's not the most obvious process. We have a bazel rule that takes all our documentation content and bundles it into an npm package, then we install that npm package into the docs site. So you would do this:

# in angular/components, build the npm package
yarn bazel build src/components-examples:npm_package

# copy the output from bazel's bin directory to somewhere more useful
cp -r $(yarn --silent bazel info bazel-bin)/src/components-examples/npm_package /tmp/docs-content/

# pack the docs content package into a .tgz file for easy consumption
cd /tmp
npm pack ./docs-content

# in the angular/material.angular.io repo, install that .tgz file
yarn add /tmp/angular-components-examples-0.0.0.tgz

We should probably make a script that does this more easily (cc @devversion )

[howardjing]

Thanks for the detailed instructions! Looks like it works.