Generate FidesJS SDK Reference Docs from tsdoc comments #4736
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎ 1 Ignored Deployment
|
Passing run #6909 ↗︎
Details:
Review all test suite changes for PR #4736 ↗︎ |
||||||||||||||||||||
NevilleS
changed the title
NevilleS
changed the title
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #4736 +/- ##
=======================================
Coverage 86.64% 86.64%
=======================================
Files 338 338
Lines 19993 19993
Branches 2555 2555
=======================================
Hits 17323 17323
Misses 2201 2201
Partials 469 469 ☔ View full report in Codecov by Sentry. |
| export type TcfCookieKeyConsent = { | ||
| [id: string | number]: boolean | undefined; | ||
| }; | ||
| export type TcfSystemsConsent = Record<string | number, boolean>; |
| import { FIDES_OVERRIDE_OPTIONS_VALIDATOR_MAP } from "./consent-constants"; | ||
| import { setupExtensions } from "./extensions"; | ||
| import { | ||
| noticeHasConsentInCookie, | ||
| transformConsentToFidesUserPreference, | ||
| } from "./shared-consent-utils"; | ||
| import type { Fides } from "../docs"; |
There was a problem hiding this comment.
Having a dependency on the docs in this part of the code is concerning. Can this typing be moved to a more generic/shared part of the code?
There was a problem hiding this comment.
I think that's fair - I was also surprised to find that we defined the "Fides Global" interface in this file and not our big "consent-types" file that has everything else.
|
|
||
| We use [Typedoc](https://typedoc.org/) to generate "FidesJS SDK Reference" docs that explain how to use the `fides.js` script in a customer website. You can find those docs here: [docs/README.md](./docs/README.md) | ||
|
|
||
| To regenerate the developer docs, run `npm run docs:generate`. |
There was a problem hiding this comment.
Nice, thanks for adding this!
|
Do you know why this 
|
That's coming from the types in For these docs I felt like documenting the details of the Once I re-run |
Closes PROD-1815
Description Of Changes
This establishes a new directory,
src/docs, which is meant to act as the external-facing type docs for using FidesJS. These types are heavily commented using TSDoc and then converted into Markdown docs using Typedoc to populate the top-leveldocs/folder 👍. As a final step, you can then runnpm run docs:importin ourfidesdocsproject to import these docs into the FidesJS SDK Reference section here: https://ethyca.com/docs/dev-docs/js/reference/READMEThe bulk of the changes here are all about renaming and cleaning up some of the types used within the
fides-jsproject to be more clear. As much as possible I've taken the strategy of having our types extend thesrc/docs/...types so that we can be more specific in the code than what is reflected in the dev docs.Code Changes
The most significant change here is some renaming of a bunch of types that I felt had lost some of their meaning...
Fides.consentobject isn't really about the cookie: it's a map ofnotice_key-> `trueFidesIdentityinstead ofFidesJSIdentitybut felt like reminding us that this was the structure used in the JS library felt helpful...?Fideswas such an interchangeable type in this codebase that it felt likeFidesGlobalat least hinted at what it was used for. I reserved theFidesinterface name for the documented interface and ended up doing a littleexport interface FidesGlobal extends Fides { ... }in the codefides_overridesobject / query params / etc. To an engineer integrating FidesJS into their website, those are the options available to them, so calling them "overrides" felt overly intimidating.typedoclibrary to generate docs from tsdoc comments in./src/docsto./docsdocs:generatenpm task to generate docs, and run that after every buildPre-Merge Checklist
CHANGELOG.md