Set up docgen for rules-unit-testing #5419

hsubox76 · 2021-08-30T23:58:36Z

Set up api-extractor to generate reference docs for rules-unit-testing.

This runs as part of the main docgen script, in order to generate links to other packages dynamically. In order to enable being a in a separate directory, some post-processing steps are done, so this is the process:

generate all docs in the repo, both JS SDK and RUT, to enable api-documenter to create links across packages.
generate a set of docs from the RUT json only (only to get a separate RUT index.md) into a dedicated docs-rut folder. Any docs with links to other packages will be broken, but that is okay because
move RUT docs with properly generated links from main docs folder into docs-rut folder
modify paths to storage/firestore/database to point to a sibling directory

To generate docs, from the top level directory run yarn docgen:exp devsite. The resulting html docs will be in a gitignored folder, rut-docs.

Note: I decided to use the direct link to the service reference doc when talking about the instance in general, and use string literals when referring to Firestore etc. as a return type, as I guess it actually returns compat instances, where it seems wrong to imply that's what the link is going to.

changeset-bot · 2021-08-30T23:58:39Z

⚠️ No Changeset found

Latest commit: e2bae00

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

github-actions · 2021-08-31T00:01:37Z

Changeset File Check ✅

No modified packages are missing from the changeset file.
No changeset formatting errors detected.

google-oss-bot · 2021-08-31T00:16:32Z

Size Analysis Report

Affected Products

No changes between base commit (e456d00) and head commit (8b90630).

Test Logs

packages/rules-unit-testing/src/public_types/index.ts

markarndt

Just one docstring correction.

packages/rules-unit-testing/src/initialize.ts

Feiyang1 · 2021-09-20T23:49:21Z

packages/rules-unit-testing/api-extractor.json

+    // Point it to your entry point d.ts file. 
+    "mainEntryPointFilePath": "<projectFolder>/dist/index.d.ts",
+    "dtsRollup": {
+        "enabled": true,


Do they need dts rollup?

I guess not, removed.

Feiyang1 · 2021-09-20T23:50:00Z

packages/rules-unit-testing/package.json

@@ -16,7 +16,8 @@
    "dev": "rollup -c -w",
    "test:nyc": "TS_NODE_CACHE=NO TS_NODE_COMPILER_OPTIONS='{\"module\":\"commonjs\"}' nyc --reporter lcovonly -- mocha 'test/{,!(browser)/**/}*.test.ts' --config ./mocharc.node.js",
    "test": "(cd functions && yarn) && firebase --project=demo-foo --debug emulators:exec 'yarn test:nyc'",
-    "test:ci": "node ../../scripts/run_tests_in_ci.js -s test"
+    "test:ci": "node ../../scripts/run_tests_in_ci.js -s test",
+    "api-report": "api-extractor run --local --verbose"


Can you add a command to generate docs locally, like other packages?

Feiyang1 · 2021-09-20T23:56:09Z

scripts/docgen/docgen.ts

+) {
+  const rulesOutputFolder = `${projectRoot}/docs-rut`;
+
+  // Generate from rules-unit-testing.api.json only, to get an index.md.


I don't think we need this index file since it will only contain one package. The rules-unit-testing.md can be used as the entry point directly.

It's possible that the top level file needs to be named index.md for devsite, so I will check about that. If so, I can rename rules-unit-testing.md (and all links to it).

So it turns out the way the devsite files are structured, it also doesn't need the index.md, so just removed this.

Feiyang1 · 2021-09-23T18:52:15Z

packages/auth/api-extractor.json

@@ -1,6 +1,6 @@
 {
    "extends": "../../config/api-extractor.json",
-    "mainEntryPointFilePath": "<projectFolder>/dist/esm5/index.d.ts",
+    "mainEntryPointFilePath": "<projectFolder>/dist/esm5/index.doc.d.ts",


Is it a mistake?

Yes, must be an artifact of running global docgen and not completing the script. Removed.

packages/rules-unit-testing/package.json

yarn.lock

google-oss-bot · 2021-10-05T19:57:07Z

Binary Size Report

Affected SDKs

No changes between base commit (e456d00) and head commit (8b90630).

Test Logs

Base (e456d00a): https://github.com/firebase/firebase-js-sdk/actions/runs/1308876220
Head (8b90630d): https://github.com/firebase/firebase-js-sdk/actions/runs/1309134722

hsubox76 requested review from avolkovi, Feiyang1, hiranya911, sam-gc and yuchenshi as code owners August 30, 2021 23:58

google-oss-bot added the doc-changes PRs that affect docs label Aug 31, 2021

github-actions bot assigned egilmorez Aug 31, 2021

yuchenshi reviewed Aug 31, 2021

View reviewed changes

packages/rules-unit-testing/src/public_types/index.ts Outdated Show resolved Hide resolved

yuchenshi reviewed Aug 31, 2021

View reviewed changes

packages/rules-unit-testing/src/public_types/index.ts Outdated Show resolved Hide resolved

yuchenshi reviewed Aug 31, 2021

View reviewed changes

packages/rules-unit-testing/src/public_types/index.ts Outdated Show resolved Hide resolved

yuchenshi approved these changes Sep 2, 2021

View reviewed changes

hsubox76 force-pushed the ch-rut-docs branch from 8eedb04 to 1507591 Compare September 2, 2021 16:26

markarndt approved these changes Sep 2, 2021

View reviewed changes

packages/rules-unit-testing/src/initialize.ts Outdated Show resolved Hide resolved

hsubox76 assigned Feiyang1 Sep 13, 2021

hsubox76 changed the title ~~WIP: Set up docgen for rules-unit-testing~~ Set up docgen for rules-unit-testing Sep 13, 2021

Feiyang1 reviewed Sep 20, 2021

View reviewed changes

Feiyang1 assigned hsubox76 and unassigned Feiyang1 Sep 20, 2021

hsubox76 force-pushed the ch-rut-docs branch from fae7537 to 39f2978 Compare September 21, 2021 18:21

hsubox76 requested a review from lisajian as a code owner September 21, 2021 18:21

hsubox76 assigned Feiyang1 and unassigned egilmorez and hsubox76 Sep 22, 2021

Feiyang1 reviewed Oct 4, 2021

View reviewed changes

Feiyang1 assigned hsubox76 and unassigned Feiyang1 Oct 4, 2021

Set up RUT docgen

e26f85d

hsubox76 added 15 commits October 5, 2021 12:28

Make it a separate task

10f48c3

Generate docs

0ede55c

Generate RUT docs with other docs

24fa82c

prettier

d79a9c7

Write into a sibling directory

338a3d0

Change pathing

143df5f

prettier

6657f48

address PR comment

e9f5ebe

Address PR comments

77e8419

prettier

b4a0b8c

Test run

1c12cd5

Don't bother creating index.md'

e563501

Revert extra changes

472fce6

prettier

95c425d

add api-report to build

360c8ff

hsubox76 force-pushed the ch-rut-docs branch from d297c77 to 360c8ff Compare October 5, 2021 19:36

google-cla bot added the cla: yes label Oct 5, 2021

hsubox76 assigned Feiyang1 and unassigned hsubox76 Oct 5, 2021

Update API reports

e2bae00

Feiyang1 approved these changes Oct 14, 2021

View reviewed changes

Feiyang1 assigned hsubox76 and unassigned Feiyang1 Oct 14, 2021

hsubox76 merged commit 5a9a144 into master Oct 14, 2021

hsubox76 deleted the ch-rut-docs branch October 14, 2021 18:01

firebase locked and limited conversation to collaborators Nov 14, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Set up docgen for rules-unit-testing #5419

Set up docgen for rules-unit-testing #5419

hsubox76 commented Aug 30, 2021 •

edited

Loading

changeset-bot bot commented Aug 30, 2021 •

edited

Loading

github-actions bot commented Aug 31, 2021 •

edited

Loading

google-oss-bot commented Aug 31, 2021 •

edited

Loading

Affected Products

Test Logs

markarndt left a comment

Feiyang1 Sep 20, 2021

hsubox76 Sep 21, 2021

Feiyang1 Sep 20, 2021

hsubox76 Sep 21, 2021

Feiyang1 Sep 20, 2021

hsubox76 Sep 21, 2021

hsubox76 Sep 21, 2021

Feiyang1 Sep 23, 2021

hsubox76 Oct 5, 2021

google-oss-bot commented Oct 5, 2021 •

edited

Loading

Set up docgen for rules-unit-testing #5419

Set up docgen for rules-unit-testing #5419

Conversation

hsubox76 commented Aug 30, 2021 • edited Loading

changeset-bot bot commented Aug 30, 2021 • edited Loading

⚠️ No Changeset found

github-actions bot commented Aug 31, 2021 • edited Loading

Changeset File Check ✅

google-oss-bot commented Aug 31, 2021 • edited Loading

Size Analysis Report

Affected Products

Test Logs

markarndt left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

google-oss-bot commented Oct 5, 2021 • edited Loading

Binary Size Report

Affected SDKs

Test Logs

hsubox76 commented Aug 30, 2021 •

edited

Loading

changeset-bot bot commented Aug 30, 2021 •

edited

Loading

github-actions bot commented Aug 31, 2021 •

edited

Loading

google-oss-bot commented Aug 31, 2021 •

edited

Loading

google-oss-bot commented Oct 5, 2021 •

edited

Loading