From 4f55ae2f5c8bde6f64b76a1ea2cded5c4fadd286 Mon Sep 17 00:00:00 2001 From: DellaBitta Date: Mon, 18 Dec 2023 13:08:36 -0500 Subject: [PATCH] [Docs] Documentation generation instructions updated in CONTRIBUTING.md (#7881) This change updates the CONTRIBUTING.md file to better instruct users how to generate reference docs. I noticed that the instructions to generate documentation was missing a command line argument. Additionally, upon review from @hsubox76, the documentation included instructions that were for the legacy compat docs, not the new modular docs --- CONTRIBUTING.md | 40 ++++++++-------------------------------- 1 file changed, 8 insertions(+), 32 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 65fcb565c41..b9cc6c21260 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -221,49 +221,25 @@ formatting guidelines. In your local build environment, please run the code form by executing the command `yarn format`. Once the code is formatted, commit the changes and push your branch. The push should cause the CI to re-check your PR's changes. -### Generating Documentation HTML Files +# Generating Documentation HTML Files If the Doc Change Check fails in your PR, it indicates that the documentation has not been generated -correctly for the changes. In your local build environment, please run `yarn docgen devsite` to -generate the documentation locally. Once the documentation has been generated, commit the changes -and push your branch. The push should cause the CI to re-check your PR's changes. - -In order to generate the HTML documentation files locally, go to the root of this repo, and run: - -``` -yarn install -yarn docgen -``` - -This will generate both js and node (client) reference docs. To just generate js -docs, replace the last line with: +correctly for the changes. In your local build environment, please run the following commands in the +root directory to generate the documentation locally: ``` -yarn docgen:js +yarn +yarn docgen devsite ``` -To just generate node docs, replace the last line with: - -``` -yarn docgen:node -``` - -Files will be written to `scripts/docgen/html` - js docs will go into the `/js` -subdirectory and node docs into the `/node` subdirectory. +This will generate reference docs 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. **NOTE:** These files are formatted to be inserted into Google's documentation site, which adds some styling and navigation, so the raw files will be missing navigation elements and may not look polished. However, it should be enough to preview the content. -This process will generate warnings for files that are generated but not listed in the `toc.yaml`, -or files that are in the `toc.yaml` but were not generated (which means something is missing in -`index.d.ts`). If this happens during the JS documentation generation, it probably means either the -`toc.yaml` or `index.d.ts` is incorrect. But in the Node process, some generated files not being -found in `toc.yaml` are to be expected, since Node documentation is a subset of the full JS -documentation. - -Follow the [PR submission guidelines](#submit) above to submit any documentation changes. - [archive]: https://github.com/firebase/firebase-js-sdk/issues?utf8=%E2%9C%93&q=is%3Aissue [file-an-issue]: https://github.com/firebase/firebase-js-sdk/issues/new [firebase-google-group]: https://groups.google.com/forum/#!forum/firebase-talk