Implement automated reference documentation generation #20
Conversation
There was a problem hiding this comment.
I just left two small comments. Overall I think these are well formatted and easy to follow, and the relative linking works well. Like I mentioned in my other comment, Erin brought to my attention that we unfortunately can't use GitHub Pages for commercial use, so that complicates things here. I think even if we were to copy and paste the files generated in this MR into the developer portal, though, that would work reasonably well as a last resort. Thank you so much for getting this working!
|
Let's not manually edit the reference docs just yet. I will look into maybe choosing a better docs generator two weeks from now but for now this is good enough, I think. |
| @@ -1,19 +1,41 @@ | |||
| /** | |||
| Module defining the Secrets API. | |||
There was a problem hiding this comment.
Sorry to be late to this, but I just caught that some of these module descriptions don't appear on the .md files. Then, after digging further, I didn't find these code comments on main. Do you know where these are being sourced from? I'd like to edit them and also make sure they're consistently appearing in the markdown versions.
There was a problem hiding this comment.
For now they are not sourced from anywhere, so they can be edited in-place here.
| @@ -1,3 +1,7 @@ | |||
| /** | |||
| Module containing the 1Password SDK Client, which can be used to authenticate and access data stored in 1Password programmatically. | |||
There was a problem hiding this comment.
| Module containing the 1Password SDK Client, which can be used to authenticate and access data stored in 1Password programmatically. | |
| Module containing the 1Password SDK client, which can be used to authenticate and access data stored in 1Password programmatically. |
I don't think we need to capitalize "client" in this context, since the client isn't a separate product.
| import * as os from "os"; | ||
| import { ClientAuthConfig } from "./core.js"; | ||
|
|
||
| const LANGUAGE = "JS"; | ||
| const VERSION = "0010001"; // v0.1.0 | ||
|
|
||
| // Contains information necessary to configure an SDK client. | ||
| /** | ||
| Defines all parameters that can be used to configure the 1Password SDK Client. |
There was a problem hiding this comment.
| Defines all parameters that can be used to configure the 1Password SDK Client. | |
| Defines all parameters that can be used to configure the 1Password SDK client. |
| @@ -1,6 +1,13 @@ | |||
| /** | |||
| Internal module defining the 1Password SDK Core. Users of the SDK should import and use the `client` module instead of this one. | |||
There was a problem hiding this comment.
| Internal module defining the 1Password SDK Core. Users of the SDK should import and use the `client` module instead of this one. | |
| Internal module defining the 1Password SDK core. You should import and use the `client` module instead of this one. |
| /** | ||
| Module defining the Secrets API. | ||
| The Secrets API can be used to access secrets stored in 1Password via secret references (op://vault/item/field). | ||
| It is implemented by the 1Passwor |
There was a problem hiding this comment.
What are we trying to say with the third line here?
This PR sets up the
npm run gen-docsscript which can be used to automatically generate markdown reference docs based on the doc comments in the SDK's code.