Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Add SDK Typedoc Implementation for v3 Client #701

Merged
merged 13 commits into from
May 14, 2024
Merged

Add SDK Typedoc Implementation for v3 Client #701

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
6a4066d
chore(sdk-client-v3): add sdk-client-v3 implementation
ajimae May 9, 2024
94599b8
chore(tsconfig.json): update tsconfig.json file
ajimae May 9, 2024
0de3194
chore(tsconfig.json): update tsconfig.json file
ajimae May 9, 2024
6a83e90
chore(tsconfig.json): update actions workflow file
ajimae May 9, 2024
05a917d
chore(tsconfig.json): update actions workflow file
ajimae May 9, 2024
f91c2ae
chore(tsconfig.json): update actions workflow file
ajimae May 9, 2024
b19c045
chore(tsconfig.json): update actions workflow file
ajimae May 9, 2024
11b3af6
chore(tsconfig.json): update actions workflow file
ajimae May 9, 2024
5eceb32
Update tsconfig.base.json
ajimae May 13, 2024
acd0f49
chore(doc.yml): update doc.yml file
ajimae May 13, 2024
d9959f9
Merge branch 'master' into feat/implement-complete-sdk-specs-v3
ajimae May 13, 2024
ffe5276
Apply suggestions from code review
jenschude May 14, 2024
4140086
chore(docs): emit docs for all packages
jenschude May 14, 2024
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
13 changes: 5 additions & 8 deletions .github/workflows/docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,13 @@
name: SDK Type Docs Specification
on:
push:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you explain why you removed this part? Will it now be deployed on every PR?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was remove because of double deployment, as it will be deployed both for all PRs and also when the PR is merged which I don't think is necessary.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And it will be available in GH pages? How will it ensure that PR won‘t overwrite the current docs on master if there is only 1 URL for the GH pages?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure I understand, but how it works is that any changes made through a PR will build a new version of the docs and deploy it to gh-pages. This is to ensure that whatever modification is made to the SDK will automatically be updated in the docs.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And also, there is no docs in the master, all the docs are built and deployed to gh-pages during PR builds.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But then if the docs changes in PR is deployed to the gh-pages, the docs will be available to the users, but they will not see the correct classes in the sdk because the PR is not merged to master?

This doesn't matter, it is not as if the PR will take forever before it is merged. I think the time between raising the PR and getting it merged is relatively short to worry about this scenario.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well that is not how the official docs work, if we have to look at it this way, the javadoc doesn't show any deployment in the PR to see how the docs looks like, I don't think we should go with that approach.

The official docs gives you a preview link which can be inspected to see the changes before the PR is merged, I think this is a better approach than the javadocs implementation.

I agree, so this GH pages link is for a preview only?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well that is not how the official docs work, if we have to look at it this way, the javadoc doesn't show any deployment in the PR to see how the docs looks like, I don't think we should go with that approach.
The official docs gives you a preview link which can be inspected to see the changes before the PR is merged, I think this is a better approach than the javadocs implementation.

I agree, so this GH pages link is for a preview only?

No, it's not only for previews, it's also the live gh-pages link. I can change the trigger to merge or release only, but doing this, we will lose our ability to see the updated docs before merging the PR (no preview deployment link) which was something I thought about before going with the PR trigger approach.

But if you still think we should deploy it on merge or release, then we can talk to the team about it to see which approach is more favourable.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let‘s discuss it in the tooling weekly 👍

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you mixed up the docs website with the ones for the SDK. The docs website publishes a preview for every PR using vercel. This is not the case for the SDK docs.

In the Java Repo we built the docs only for the main branch to see that it's not broken, but there is no deployment happening.

Deploy to the the GH pages happens only after a tag has been made or the build was triggered manually. This should be sufficient as the docs are mainly auto generated. Only manually written docs are sometimes built locally to check the look.

branches: master

pull_request:
branches:
- master
workflow_dispatch:
repository_dispatch:
jenschude marked this conversation as resolved.
Show resolved Hide resolved
types: [new_release]

jobs:
# Build job
build:
# run only when release succeeded
concurrency: ci-${{ github.ref }}
runs-on: ubuntu-latest
steps:
Expand Down Expand Up @@ -52,9 +50,8 @@ jobs:
- name: Upload artifact 🗂
uses: actions/upload-pages-artifact@v3
with:
# Upload entire repository
path: .

- name: Deploy to GitHub Pages 🚀
id: deployment
uses: actions/deploy-pages@v4 # or specific "vX.X.X" version tag for this actio
uses: actions/deploy-pages@v4
5 changes: 5 additions & 0 deletions .github/workflows/release.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,11 @@ jobs:
env:
GITHUB_TOKEN: ${{ steps.generate_github_token.outputs.token }}

- name: Dispatch repository event
if: steps.changesets.outputs.published == 'true'
run: |
gh api --method POST /repos/commercetools/commercetools-typescript-sdk/dispatches -f "event_type=new_release"

- name: Convert markdown to slack markdown
uses: LoveToKnow/[email protected]
id: markdown
Expand Down
8 changes: 8 additions & 0 deletions packages/history-sdk/tsconfig.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"rootDir": "src",
"outDir": "dist"
},
"include": ["src"]
}
5 changes: 5 additions & 0 deletions packages/history-sdk/typedoc.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"name": "History API SDK",
"extends": ["../../typedoc.base.json"],
"entryPoints": ["src/index.ts"]
}
8 changes: 8 additions & 0 deletions packages/importapi-sdk/tsconfig.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"rootDir": "src",
"outDir": "dist"
},
"include": ["src"]
}
5 changes: 5 additions & 0 deletions packages/importapi-sdk/typedoc.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"name": "Import API SDK",
"extends": ["../../typedoc.base.json"],
"entryPoints": ["src/index.ts"]
}
8 changes: 8 additions & 0 deletions packages/platform-sdk/tsconfig.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"rootDir": "src",
"outDir": "dist"
},
"include": ["src"]
}
5 changes: 5 additions & 0 deletions packages/platform-sdk/typedoc.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"name": "Platform SDK",
"extends": ["../../typedoc.base.json"],
"entryPoints": ["src/index.ts"]
}
3 changes: 2 additions & 1 deletion packages/sdk-client-v3/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@
"scripts": {
"organize_imports": "find src -type f -name '*.ts' | xargs organize-imports-cli",
"postbuild": "yarn organize_imports",
"post_process_generate": "yarn organize_imports"
"post_process_generate": "yarn organize_imports",
"docs": "typedoc --out docs"
}
}
8 changes: 8 additions & 0 deletions packages/sdk-client-v3/tsconfig.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"rootDir": "src",
"outDir": "dist"
},
"include": ["src"]
}
5 changes: 5 additions & 0 deletions packages/sdk-client-v3/typedoc.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"name": "Client v3",
"extends": ["../../typedoc.base.json"],
"entryPoints": ["src/index.ts"]
}
3 changes: 2 additions & 1 deletion packages/sdk-client/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@
"scripts": {
"organize_imports": "find src -type f -name '*.ts' | xargs organize-imports-cli",
"postbuild": "yarn organize_imports",
"post_process_generate": "yarn organize_imports"
"post_process_generate": "yarn organize_imports",
"docs": "typedoc --out docs"
}
}
8 changes: 8 additions & 0 deletions packages/sdk-client/tsconfig.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"rootDir": "src",
"outDir": "dist"
},
"include": ["src"]
}
5 changes: 5 additions & 0 deletions packages/sdk-client/typedoc.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"name": "Client v2",
"extends": ["../../typedoc.base.json"],
"entryPoints": ["src/index.ts"]
}
8 changes: 8 additions & 0 deletions packages/ts-sdk-apm/tsconfig.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"rootDir": "src",
"outDir": "dist"
},
"include": ["src"]
}
5 changes: 5 additions & 0 deletions packages/ts-sdk-apm/typedoc.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"name": "APM",
"extends": ["../../typedoc.base.json"],
"entryPoints": ["src/index.ts"]
}
11 changes: 11 additions & 0 deletions tsconfig.base.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
{
"compilerOptions": {
"module": "Node16",
"strict": false,
"composite": true,
"resolveJsonModule": true,

"declaration": true,
"declarationMap": true
}
}
10 changes: 9 additions & 1 deletion tsconfig.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,5 +10,13 @@
"resolveJsonModule": true,
"downlevelIteration": true
},
"exclude": ["./examples/"]
"exclude": ["./examples/"],
"references": [
{
"path": "./packages/sdk-client"
},
{
"path": "./packages/sdk-client-v3"
}
]
}
12 changes: 12 additions & 0 deletions typedoc.base.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
{
"$schema": "https://typedoc.org/schema.json",
"kindSortOrder": [
"Project",
"Module",
"Class",
"Function",
"Interface",
"TypeAlias"
],
"includeVersion": false
}
6 changes: 4 additions & 2 deletions typedoc.cjs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
module.exports = {
entryPoints: ['packages/sdk-client/src'],
out: 'docs',
entryPoints: ['packages/*'],
name: 'Typescript SDK Type Docs',
entryPointStrategy: 'packages',
includeVersion: false,
visibilityFilters: {
protected: true,
private: true,
Expand Down
Loading