Skip to content

Simplify check for reference doc changes #7014

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 12 commits into from
Feb 22, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .github/CODEOWNERS
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,7 @@ packages/app-check-interop-types @hsubox76 @firebase/jssdk-global-approvers
# Documentation Changes
packages/firebase/index.d.ts @egilmorez @firebase/jssdk-global-approvers
scripts/docgen/content-sources/ @egilmorez @firebase/jssdk-global-approvers
docs-devsite/ @egilmorez @markarndt
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think Mark has write access to this repo? cc: @markarndt

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've added him, let me know if any other tech writers ought to be added.


# Changeset
.changeset @egilmorez @firebase/jssdk-changeset-approvers @firebase/firestore-js-team @firebase/jssdk-global-approvers
.changeset @firebase/jssdk-changeset-approvers @firebase/firestore-js-team @firebase/jssdk-global-approvers
28 changes: 28 additions & 0 deletions .github/workflows/check-docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
name: Doc Change Check (Run "yarn docgen devsite" if this fails)

on: pull_request

jobs:
doc-check:
name: Check if reference docs have changed
runs-on: ubuntu-latest

steps:
- name: Checkout Repo
uses: actions/checkout@master
with:
# get all history for the diff
fetch-depth: 0
- name: Set up Node (14)
uses: actions/setup-node@v2
with:
node-version: 14.x
- name: Yarn install
run: yarn
- name: Run doc generation (devsite docs)
run: yarn docgen devsite
- name: Check for changes in docs-devsite dir (fail if so)
run: git diff --exit-code docs-devsite
- name: Reference documentation needs to be updated. See message below.
if: ${{ failure() }}
run: echo "Changes in this PR affect the reference docs. Run \`yarn docgen devsite\` locally to regenerate docs and add them to this PR."
41 changes: 0 additions & 41 deletions .github/workflows/label-doc-changes.yml

This file was deleted.

4 changes: 2 additions & 2 deletions docs-devsite/firestore_.aggregatefield.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ export declare class AggregateField<T>

| Property | Modifiers | Type | Description |
| --- | --- | --- | --- |
| [type](./firestore_.aggregatefield.md#aggregatefieldtype) | | string | A type string to uniquely identify instances of this class. |
| [type](./firestore_.aggregatefield.md#aggregatefieldtype) | | (not declared) | A type string to uniquely identify instances of this class. |

## AggregateField.type

Expand All @@ -31,5 +31,5 @@ A type string to uniquely identify instances of this class.
<b>Signature:</b>

```typescript
type: string;
readonly type = "AggregateField";
```
2 changes: 1 addition & 1 deletion docs-devsite/firestore_.aggregatespec.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ https://github.com/firebase/firebase-js-sdk
{% endcomment %}

# AggregateSpec interface
A type whose property values are all `AggregateField` objects.
Specifies a set of aggregations and their aliases.

<b>Signature:</b>

Expand Down
4 changes: 2 additions & 2 deletions docs-devsite/firestore_.md
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,7 @@ https://github.com/firebase/firebase-js-sdk

| Interface | Description |
| --- | --- |
| [AggregateSpec](./firestore_.aggregatespec.md#aggregatespec_interface) | A type whose property values are all <code>AggregateField</code> objects. |
| [AggregateSpec](./firestore_.aggregatespec.md#aggregatespec_interface) | Specifies a set of aggregations and their aliases. |
| [DocumentChange](./firestore_.documentchange.md#documentchange_interface) | A <code>DocumentChange</code> represents a change to the documents matching a query. It contains the document affected and the type of change that occurred. |
| [DocumentData](./firestore_.documentdata.md#documentdata_interface) | Document data (for use with [setDoc()](./firestore_lite.md#setdoc)<!-- -->) consists of fields mapped to values. |
| [FirestoreDataConverter](./firestore_.firestoredataconverter.md#firestoredataconverter_interface) | Converter used by <code>withConverter()</code> to transform user objects of type <code>T</code> into Firestore data.<!-- -->Using the converter allows you to specify generic type arguments when storing and retrieving objects from Firestore. |
Expand Down Expand Up @@ -1946,7 +1946,7 @@ The union of all `AggregateField` types that are supported by Firestore.
<b>Signature:</b>

```typescript
export declare type AggregateFieldType = AggregateField<number>;
export declare type AggregateFieldType = AggregateField<number | null>;
```

## AggregateSpecData
Expand Down
4 changes: 2 additions & 2 deletions docs-devsite/firestore_lite.aggregatefield.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ export declare class AggregateField<T>

| Property | Modifiers | Type | Description |
| --- | --- | --- | --- |
| [type](./firestore_lite.aggregatefield.md#aggregatefieldtype) | | string | A type string to uniquely identify instances of this class. |
| [type](./firestore_lite.aggregatefield.md#aggregatefieldtype) | | (not declared) | A type string to uniquely identify instances of this class. |

## AggregateField.type

Expand All @@ -31,5 +31,5 @@ A type string to uniquely identify instances of this class.
<b>Signature:</b>

```typescript
type: string;
readonly type = "AggregateField";
```
2 changes: 1 addition & 1 deletion docs-devsite/firestore_lite.aggregatespec.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ https://github.com/firebase/firebase-js-sdk
{% endcomment %}

# AggregateSpec interface
A type whose property values are all `AggregateField` objects.
Specifies a set of aggregations and their aliases.

<b>Signature:</b>

Expand Down
4 changes: 2 additions & 2 deletions docs-devsite/firestore_lite.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ https://github.com/firebase/firebase-js-sdk

| Interface | Description |
| --- | --- |
| [AggregateSpec](./firestore_lite.aggregatespec.md#aggregatespec_interface) | A type whose property values are all <code>AggregateField</code> objects. |
| [AggregateSpec](./firestore_lite.aggregatespec.md#aggregatespec_interface) | Specifies a set of aggregations and their aliases. |
| [DocumentData](./firestore_lite.documentdata.md#documentdata_interface) | Document data (for use with [setDoc()](./firestore_lite.md#setdoc)<!-- -->) consists of fields mapped to values. |
| [FirestoreDataConverter](./firestore_lite.firestoredataconverter.md#firestoredataconverter_interface) | Converter used by <code>withConverter()</code> to transform user objects of type <code>T</code> into Firestore data.<!-- -->Using the converter allows you to specify generic type arguments when storing and retrieving objects from Firestore. |
| [Settings](./firestore_lite.settings.md#settings_interface) | Specifies custom configurations for your Cloud Firestore instance. You must set these before invoking any other methods. |
Expand Down Expand Up @@ -1277,7 +1277,7 @@ The union of all `AggregateField` types that are supported by Firestore.
<b>Signature:</b>

```typescript
export declare type AggregateFieldType = AggregateField<number>;
export declare type AggregateFieldType = AggregateField<number | null>;
```

## AggregateSpecData
Expand Down
33 changes: 28 additions & 5 deletions scripts/docgen/docgen.ts
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,11 @@ async function generateDocs(
`${projectRoot}/packages/auth/api-extractor.json`,
'utf8'
);
// Save original auth.md as well.
const authApiReportOriginal = fs.readFileSync(
`${projectRoot}/common/api-review/auth.api.md`,
'utf8'
);
const authApiConfigModified = authApiConfigOriginal.replace(
`"mainEntryPointFilePath": "<projectFolder>/dist/esm5/index.d.ts"`,
`"mainEntryPointFilePath": "<projectFolder>/dist/esm5/index.doc.d.ts"`
Expand All @@ -145,21 +150,39 @@ async function generateDocs(
authApiConfigModified
);

if (!skipBuild) {
await spawn('yarn', ['build'], {
stdio: 'inherit'
});

if (skipBuild) {
await spawn('yarn', ['api-report'], {
stdio: 'inherit'
});
} else {
// api-report is run as part of every build
await spawn(
'yarn',
[
'lerna',
'run',
'--scope',
'@firebase/*',
'--ignore',
'@firebase/*-compat',
'build'
],
{
stdio: 'inherit'
}
);
}

// Restore original auth api-extractor.json contents.
fs.writeFileSync(
`${projectRoot}/packages/auth/api-extractor.json`,
authApiConfigOriginal
);
// Restore original auth.api.md
fs.writeFileSync(
`${projectRoot}/common/api-review/auth.api.md`,
authApiReportOriginal
);

if (!fs.existsSync(tmpDir)) {
fs.mkdirSync(tmpDir);
Expand Down