Skip to content

Commit

Permalink
[Docs] Documentation generation instructions updated in CONTRIBUTING.…
Browse files Browse the repository at this point in the history
…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
  • Loading branch information
DellaBitta committed Dec 18, 2023
1 parent f5882cb commit 4f55ae2
Showing 1 changed file with 8 additions and 32 deletions.
40 changes: 8 additions & 32 deletions CONTRIBUTING.md
Expand Up @@ -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
Expand Down

0 comments on commit 4f55ae2

Please sign in to comment.