Skip to content

[Docs] Documentation generation instructions updated in CONTRIBUTING.md #7881

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 3 commits into from
Dec 18, 2023
Merged
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
40 changes: 8 additions & 32 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
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