docs: publish a close-to-stock typedoc reference site to GitHub Pages, manually or on publish

.github/workflows/deploy-api-reference.yml

@@ -0,0 +1,37 @@
+name: Deploy API Reference
+on:
+  workflow_dispatch:
+jobs:
+  deploy-api-reference:
+    name: 'Deploy API Reference'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v6
+        with:
+          node-version: lts/*
+          registry-url: 'https://registry.npmjs.org'
+      - name: Install latest NPM
+        run: |
+          npm --version
+          npm install -g npm@latest
+          npm --version
+      - name: Yarn Install
+        uses: nick-fields/retry@v3
+        with:
+          timeout_minutes: 15
+          retry_wait_seconds: 60
+          max_attempts: 3
+          command: yarn
+      - name: Build API reference (TypeDoc)
+        run: yarn reference:api:gh-pages
+      - name: Upload API reference artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./apidocs-out

.github/workflows/publish.yml

@@ -64,3 +64,12 @@ jobs:
           # org admin Github Token required for the changelog/tag commit+push
           # to work via an exception to branch protection rules
           GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
+
+  deploy-api-reference:
+    name: 'Deploy API Reference'
+    needs: publish_npm
+    uses: ./.github/workflows/deploy-api-reference.yml
+    permissions:
+      contents: read
+      pages: write
+      id-token: write

.gitignore

@@ -538,6 +538,8 @@ Pods/*
 packages/**/version.js
 packages/**/version.ts
 typedoc.raw.json
+reference/
+apidocs-out/
 tests/ios/Firebase
 tests/ios/resetXcode.sh
 .tmp

.spellcheck.dict.txt

@@ -132,6 +132,7 @@ NoSQL
 Notifee
 notifee
 NPE
+npm
 NPM
 OAuth
 onboarding

docs/reference-api-readme.md

@@ -0,0 +1,7 @@
+# API reference
+
+This site documents the TypeScript and JavaScript APIs for the [`react-native-firebase`](https://github.com/invertase/react-native-firebase) packages published on npm under the `@react-native-firebase/*` scope.
+
+The **app** module is required; all other modules are optional peer packages. Use the sidebar to open each package. Cross-package types (for example `FirebaseApp`) link between modules when they are part of this documentation build.
+
+For guides and setup, see the [main documentation](https://rnfirebase.io).

package.json

@@ -22,6 +22,8 @@
     "lint:spellcheck": "spellchecker --quiet --files=\"docs/**/*.md\" --dictionaries=\"./.spellcheck.dict.txt\" --reports=\"spelling.json\" --plugins spell indefinite-article repeated-words syntax-mentions syntax-urls frontmatter",
     "tsc:compile": "tsc --project .",
     "lint:all": "yarn lint && yarn lint:markdown && yarn lint:spellcheck && yarn tsc:compile",
+    "reference:api": "typedoc",
+    "reference:api:gh-pages": "typedoc --out apidocs-out --hostedBaseUrl https://invertase.github.io/react-native-firebase/ --useHostedBaseUrlForAbsoluteLinks",
     "tests:ai:mocks": "yarn ts-node ./scripts/fetch_ai_mock_responses.ts && yarn ts-node ./packages/ai/__tests__/test-utils/convert-mocks.ts",
     "tests:jest": "jest",
     "tests:jest-watch": "jest --watch",
@@ -106,6 +108,7 @@
     "spellchecker-cli": "^7.0.2",
     "ts-jest": "^29.4.6",
     "ts-node": "^10.9.2",
+    "typedoc": "^0.28.18",
     "typescript": "^5.9.3"
   },
   "resolutions": {

packages/ai/lib/index.ts

@@ -49,7 +49,7 @@ export {
 
 /**
  * Returns the default {@link AI} instance that is associated with the provided
- * {@link @firebase/app#FirebaseApp}. If no instance exists, initializes a new instance with the
+ * {@link @firebase/app!FirebaseApp}. If no instance exists, initializes a new instance with the
  * default settings.
  *
  * @example
@@ -69,9 +69,9 @@ export {
  * const ai = getAI(app, { backend: new VertexAIBackend() });
  * ```
  *
- * @param app - The {@link @firebase/app#FirebaseApp} to use.
+ * @param app - The {@link @firebase/app!FirebaseApp} to use.
  * @param options - {@link AIOptions} that configure the AI instance.
- * @returns The default {@link AI} instance for the given {@link @firebase/app#FirebaseApp}.
+ * @returns The default {@link AI} instance for the given {@link @firebase/app!FirebaseApp}.
  *
  * @public
  */

packages/ai/lib/public-types.ts

@@ -87,7 +87,7 @@ export type BackendType = (typeof BackendType)[keyof typeof BackendType];
  */
 export interface AI {
   /**
-   * The {@link @firebase/app#FirebaseApp} this {@link AI} instance is associated with.
+   * The {@link @firebase/app!FirebaseApp} this {@link AI} instance is associated with.
    */
   app: ReactNativeFirebase.FirebaseApp;
   appCheck?: FirebaseAppCheckTypes.Module | null;

packages/ai/lib/types/imagen/requests.ts

@@ -73,7 +73,7 @@ export interface ImagenGenerationConfig {
   numberOfImages?: number;
   /**
    * The aspect ratio of the generated images. The default value is square 1:1.
-   * Supported aspect ratios depend on the Imagen model, see {@link (ImagenAspectRatio:type)}
+   * Supported aspect ratios depend on the Imagen model, see {@link ImagenAspectRatio}
    * for more details.
    */
   aspectRatio?: ImagenAspectRatio;

packages/ai/lib/types/imagen/responses.ts

@@ -71,8 +71,8 @@ export interface ImagenGenerationResponse<T extends ImagenInlineImage | ImagenGC
    * The reason that images were filtered out. This property will only be defined if one
    * or more images were filtered.
    *
-   * Images may be filtered out due to the {@link (ImagenSafetyFilterLevel:type)},
-   * {@link (ImagenPersonFilterLevel:type)}, or filtering included in the model.
+   * Images may be filtered out due to the {@link ImagenSafetyFilterLevel},
+   * {@link ImagenPersonFilterLevel}, or filtering included in the model.
    * The filter levels may be adjusted in your {@link ImagenSafetySettings}.
    *
    * See the {@link https://cloud.google.com/vertex-ai/generative-ai/docs/image/responsible-ai-imagen | Responsible AI and usage guidelines for Imagen}

packages/ai/typedoc.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["lib/index.ts"],
+  "tsconfig": "tsconfig.json",
+  "intentionallyNotExported": ["ApiSettings", "WebSocketHandler"]
+}

packages/analytics/lib/modular.ts

@@ -948,10 +948,10 @@ export function initiateOnDeviceConversionMeasurementWithEmailAddress(
  * start privacy-sensitive on-device conversion management.
  * This is iOS-only.
  * This is a no-op if you do not include '$RNFirebaseAnalyticsGoogleAppMeasurementOnDeviceConversion = true' in your Podfile
+ * {@link https://firebase.google.com/docs/tutorials/ads-ios-on-device-measurement/step-3#use-hashed-credentials}
  *
  * @param analytics Analytics instance.
  * @param hashedEmailAddress sha256-hashed of normalized email address, properly formatted complete with domain name e.g, 'user@example.com'
- * @link https://firebase.google.com/docs/tutorials/ads-ios-on-device-measurement/step-3#use-hashed-credentials
  */
 export function initiateOnDeviceConversionMeasurementWithHashedEmailAddress(
   analytics: Analytics,
@@ -988,10 +988,10 @@ export function initiateOnDeviceConversionMeasurementWithPhoneNumber(
  * start privacy-sensitive on-device conversion management.
  * This is iOS-only.
  * This is a no-op if you do not include '$RNFirebaseAnalyticsGoogleAppMeasurementOnDeviceConversion = true' in your Podfile
+ * {@link https://firebase.google.com/docs/tutorials/ads-ios-on-device-measurement/step-3#use-hashed-credentials}
  *
  * @param analytics Analytics instance.
  * @param hashedPhoneNumber sha256-hashed of normalized phone number in E.164 format - that is a leading + sign, then up to 15 digits, no dashes or spaces.
- * @link https://firebase.google.com/docs/tutorials/ads-ios-on-device-measurement/step-3#use-hashed-credentials
  */
 export function initiateOnDeviceConversionMeasurementWithHashedPhoneNumber(
   analytics: Analytics,
@@ -1031,9 +1031,10 @@ export function setConsent(analytics: Analytics, consentSettings: ConsentSetting
 /**
  * Configures Firebase Analytics to use custom gtag or dataLayer names.
  * Intended to be used if gtag.js script has been installed on this page independently of Firebase Analytics, and is using non-default names for either the gtag function or for dataLayer. Must be called before calling `getAnalytics()` or it won't have any effect. Web only.
- * @param {SettingsOptions} options - See SettingsOptions.
+ * @param {SettingsOptions} _options - See SettingsOptions - currently unused.
  * @returns {void}
  */
+
 export function settings(_options: SettingsOptions): void {
   // Returns nothing until Web implemented.
 }

packages/analytics/typedoc.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["lib/modular.ts", "lib/types/analytics.ts"],
+  "tsconfig": "tsconfig.json",
+  "intentionallyNotExported": [
+    "_AddPaymentInfoEventParameters",
+    "_AddShippingInfoEventParameters",
+    "_AddShippingInfoParameters",
+    "_AddToCartEventParameters",
+    "_AddToWishlistEventParameters",
+    "_AnalyticsCallOptions",
+    "_AnalyticsSettings",
+    "_BeginCheckoutEventParameters",
+    "_CampaignDetailsEventParameters",
+    "_ConsentSettings",
+    "_EarnVirtualCurrencyEventParameters",
+    "_EventParams",
+    "_GenerateLeadEventParameters",
+    "_GtagConfigParams",
+    "_Item",
+    "_JoinGroupEventParameters",
+    "_LevelEndEventParameters",
+    "_LevelStartEventParameters",
+    "_LevelUpEventParameters",
+    "_LoginEventParameters",
+    "_PostScoreEventParameters",
+    "_PurchaseEventParameters",
+    "_RefundEventParameters",
+    "_RemoveFromCartEventParameters",
+    "_ScreenViewParameters",
+    "_SearchEventParameters",
+    "_SelectContentEventParameters",
+    "_SelectItemEventParameters",
+    "_SelectPromotionEventParameters",
+    "_SetCheckoutOptionEventParameters",
+    "_SettingsOptions",
+    "_ShareEventParameters",
+    "_SignUpEventParameters",
+    "_SpendVirtualCurrencyEventParameters",
+    "_Statics",
+    "_UnlockAchievementEventParameters",
+    "_ViewCartEventParameters",
+    "_ViewItemEventParameters",
+    "_ViewItemListEventParameters",
+    "_ViewPromotionEventParameters",
+    "_ViewSearchResultsParameters"
+  ]
+}

packages/app-check/typedoc.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["lib/modular.ts", "lib/types/appcheck.ts"],
+  "tsconfig": "tsconfig.json",
+  "intentionallyNotExported": [
+    "_AppCheck",
+    "_AppCheckListenerResult",
+    "_AppCheckOptions",
+    "_AppCheckProvider",
+    "_AppCheckStatics",
+    "_AppCheckToken",
+    "_AppCheckTokenResult",
+    "_CustomProviderOptions"
+  ]
+}

packages/app-distribution/typedoc.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["lib/modular/index.d.ts"],
+  "intentionallyNotExported": [
+    "FirebaseAppDistributionTypes.Module",
+    "FirebaseAppDistributionTypes.AppDistributionRelease"
+  ]
+}