-
Notifications
You must be signed in to change notification settings - Fork 225
Auto-generated JS API docs & TS cleanup #2313
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
Conversation
@@ -34,6 +34,7 @@ jobs: | |||
pip install wheel | |||
pip install -U -r doc/requirements.txt | |||
pip install -U -e ./python | |||
npm install typescript [email protected] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
sphinx-js doesn't support newer versions yet.
samples/apps/forum/src/ccf/util.ts
Outdated
@@ -1,94 +1,13 @@ | |||
// Copyright (c) Microsoft Corporation. All rights reserved. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Probably util
is not the best name. Since these are all KV helpers, maybe something with kv in the name?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
app.ts to match the C++ ccfapp namespace?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't think that's a good name. We may have more modules in the future and collectively they may be in the "ccfapp" namespace but modules != namespace.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Let's ignore this for now and think about it again when we make it into a library.
letmaik/js-api-docs@20568 aka 20210315.22 vs main ewma over 20 builds from 20172 to 20556 |
Two things that are unrelated to documentation but which this PR made obvious to me:
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks you for setting this up, I expect it will make the JS/TS interface considerably easier to use in practice.
Yep, I opened #2315 for that. |
Fixes #1765.
This uses sphinx-js and typedoc to generate API docs for the built-in parts of CCF. It does not (yet?) document the utility TypeScript module that can optionally be used for dealing with type conversions of KV map keys/values.
sphinx-js' TypeScript support is basic and the project acknowledges that and doesn't intend to work on it (since Mozilla doesn't use TypeScript themselves). Any improvements typically come from community PRs. I tried to work around various issues but it's not as pretty as it could be.
I also took the opportunity to split the built-in from the utility parts and move them into separate modules. There are no "automatic" breaking changes for existing apps since the original
ccf.ts
module has to be vendored.