Add docgen all script and update documentation (#8258)

* Add docgen all script and update documentation

* Move toc to devsite, and rename to `_toc.yaml`

* Fix formatting

* Remove seperate toc CI check

* Update Contributing guide

* revert changes made to refdocs

Author: dlarocque

.github/workflows/check-docs.yml

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-name: Doc Change Check (Run "yarn docgen devsite" if this fails)
+name: Doc Change Check (Run "yarn docgen:all" if this fails)
 
 on: pull_request
 
@@ -33,10 +33,10 @@ jobs:
         node-version: 20.x
     - name: Yarn install
       run: yarn
-    - name: Run doc generation (devsite docs)
-      run: yarn docgen devsite
+    - name: Run doc generation
+      run: yarn docgen:all
     - 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."
+      run: echo "Changes in this PR affect the reference docs. Run \`yarn docgen:all\` locally to regenerate docs and add them to this PR."

CONTRIBUTING.md

@@ -227,10 +227,10 @@ root directory to generate the documentation locally:
 
 ```
 yarn
-yarn docgen devsite
+yarn docgen:all
 ```
 
-This will generate reference docs in `docs-devsite/`. Commit and push the generated
+This will generate reference docs and the toc in `docs-devsite/`. Commit and push the generated
 documentation changes to GitHub following the [PR submission guidelines](#submit). Your push
 to the remote repository should force any failing documentation checks to execute again.
 

toc/toc.yaml renamed to docs-devsite/_toc.yaml

@@ -40,6 +40,7 @@
     "test:saucelabs": "node scripts/run_saucelabs.js",
     "docgen": "ts-node-script scripts/docgen/docgen.ts",
     "docgen:compat": "node scripts/docgen-compat/generate-docs.js --api js",
+    "docgen:all": "yarn docgen devsite && yarn docgen toc",
     "lint": "lerna run --scope @firebase/* lint",
     "lint:fix": "lerna run --scope @firebase/* lint:fix",
     "size-report": "ts-node-script scripts/size_report/report_binary_size.ts",

package.json

@@ -152,12 +152,18 @@ async function generateToc() {
         'toc',
         '--input',
         'temp',
+        '--output',
+        'docs-devsite',
         '-p',
         '/docs/reference/js',
         '-j'
       ],
       { stdio: 'inherit' }
     );
+    // The toc on the devsite must be named _toc.yaml
+    await spawn('mv', ['docs-devsite/toc.yaml', 'docs-devsite/_toc.yaml'], {
+      stdio: 'inherit'
+    });
   } finally {
     cleanup();
   }