feat(docs): Update documentation and documentation generation #641
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Summary of Changes
Hello @eugenioenko, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!
This pull request significantly enhances the project's documentation by introducing comprehensive JSDoc comments throughout the codebase and upgrading the documentation generation pipeline. The primary goal is to improve the clarity and usability of the generated API documentation, making it easier for developers to understand and integrate with the SDK, and to enable the generation of markdown-formatted documentation for integration with external documentation platforms.
Highlights
- Enhanced Code Documentation: I've added extensive JSDoc-style comments to key functions, classes, and types across the
lib/srcdirectory, includingaccess.ts,opentdf.ts,platform.ts,seekable.ts, andutils.ts. This improves the clarity and discoverability of the SDK's API. - Improved Documentation Generation: I've upgraded
typedocto version0.28.5and integratedtypedoc-plugin-markdownto enable the generation of documentation in markdown format. A newdoc:mdnpm script has been added to facilitate this process, which is crucial for integrating generated docs into external sites likeopentdf.io. - Dependency Updates: I've updated several development dependencies in
package-lock.jsonandpackage.json, includingtypedocand various related@babel,@shikijs, and other utility packages, ensuring compatibility and leveraging the latest features.
Using Gemini Code Assist
The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.
Invoking Gemini
You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.
| Feature | Command | Description |
|---|---|---|
| Code Review | /gemini review |
Performs a code review for the current pull request in its current state. |
| Pull Request Summary | /gemini summary |
Provides a summary of the current pull request in its current state. |
| Comment | @gemini-code-assist | Responds in comments when explicitly tagged, both in issue comments and review comments. |
| Help | /gemini help |
Displays a list of available commands. |
Customization
To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.
Limitations & Feedback
Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.
You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.
Footnotes
-
Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩
There was a problem hiding this comment.
Code Review
The pull request introduces jsdoc style comments and adds typedoc-plugin-markdown to generate docs in markdown. The changes include updates to package.json, access.ts, opentdf.ts, platform.ts, seekable.ts, and utils.ts to improve documentation and documentation generation.
eugenioenko
force-pushed
the
feat/docs-readme
branch
from
699e401 to
1285f90
Compare
|
A comparison image. Left is before and right is after
|
eugenioenko
force-pushed
the
feat/docs-readme
branch
3 times, most recently
from
f01579a to
eb5615f
Compare
docs: adds and updates some docs comments chore: adds platform client and updates more docs Signed-off-by: Eugene Yakhnenko <[email protected]>
eugenioenko
force-pushed
the
feat/docs-readme
branch
from
eb5615f to
945c4de
Compare
|
Motivation
The generated docs via typedoc here https://opentdf.github.io/web-sdk/ can be improved by adding comments in the source code and also formatting some comments into jsdoc style.
We also want to have the ability to include generated documentation into docs site here https://opentdf.io/category/sdk.
PR changes
typedoc-plugin-markdownto have the ability to use generate docs with docusaurusnpm run doc:mdwill generate the markdown docstypedoc-theme.cssto align some colors with opentdf brandNote
This PR mainly focus is improvement of the OpenTDF class documentation.
There are more areas for improvement
Dev Notes
I've explored generating the markdown docs using microsofts
api-extractor/api-documenter. Here are some conclusions