Format /api code samples (#322)

* Test v1.0 * Test 1.1 * Test v1.2 * Update types.ts * Generation example * Small adjustments * Template test * Cosmetic adjustments * Tags problem solved * v2.0 * Revert * Delete .DS_Store * v1.01 * v1.02 * Minor fix * Braces fix * Table fixes * Requested changes * Minor changes * Test commit * Update list.md * Sample request fixed * Update blueprint version * ci: Generate docs * Update .hbs pattern * Update sample response layout * Requested changes * Update SUMMARY.md * Requested changes * modified setFileContext function * Update blueprint * Update .prettierignore * Set noEscape true for hbs * Use resourceType * Use urls from root * Use relative links * Add .md extension to links * Tables removed * Remove hbs override from eslint * Update api-clients to api * fix: move files to match api file structure (#312) * Update API reference page template (#311) * Update api-reference template, add responseKey to file response context * Update blueprint package registry url * Remove license * Add eq helper * ci: Generate docs * Change default return value to {} * ci: Generate docs * Bump seam types to 1.229.1 * ci: Generate docs * Remove default value when no code samples are provided * Default to void when there's not responseKey * Add type to request params * ci: Generate docs * Bump blueprint to 0.14.0 and fix req param types * ci: Generate docs * Fix setEndpointTemplateContext * ci: Generate docs --------- Co-authored-by: Seam Bot <[email protected]> * Generate `/docs/acs/systems/README.md` with `acs_system` resource and properties (#314) * Update api-reference template, add responseKey to file response context * Update blueprint package registry url * Remove license * Add eq helper * ci: Generate docs * Change default return value to {} * ci: Generate docs * Bump seam types to 1.229.1 * ci: Generate docs * Remove default value when no code samples are provided * Default to void when there's not responseKey * Add type to request params * ci: Generate docs * Create api resource page template * Set context for resource page * Update reference.ts to actually set context for resource pages * ci: Generate docs * Add missing new line to the end of src/layouts/api-resource.hbs * Fix indentation * ci: Generate docs * Bump blueprint to 0.14.0 and fix req param types * ci: Generate docs * Fix setEndpointTemplateContext * ci: Generate docs * Update src/layouts/api-resource.hbs * ci: Generate docs * Update src/layouts/api-resource.hbs * ci: Generate docs * Update src/layouts/api-resource.hbs Co-authored-by: Evan Sosenko <[email protected]> * ci: Generate docs * Rename api-resource template to api-route + the set context fn * Rename src/layouts/api-resource.hbs to src/layouts/api-route.hbs --------- Co-authored-by: Seam Bot <[email protected]> Co-authored-by: Evan Sosenko <[email protected]> * Do not generate sdk pages (#315) * Do not generate sdk pages * Remove empty sdk files * ci: Generate docs * Update metalsmith.ts * Disable SDK gen * ci: Format code * Do not generate any SDKs * Set type * Remove sdk from src * Remove generated sdk pages --------- Co-authored-by: Seam Bot <[email protected]> * fix: update paths to match api (#313) * wip: rename paths * rename paths * revert gitbook * add missing redirect directories * revert overview.md * Apply suggestions from code review --------- Co-authored-by: Evan Sosenko <[email protected]> * Move helpers to handlebars-helpers * Replace /acs/systems ref with generated pages * Fix more old api ref paths (#317) * rename reset-workspace -> reset_sandbox * get-workspace * revoke-access-to-a-device-from-a-user-identity.md * user_identities/remove_acs_user * list_acs_users * list_acs_systems * list_accessible_devices * list-user-identities * grant_access_to_device * get-a-user-identity * list-enrollmnent-automations * launch-an-enrollment-automation.md * enrollment_automations/get * get-an-enrollment-automation.md * rename user-identities -> user_identities * rename enrollment-automations -> enrollment_automations * enrollment_automations/README.md * add user_identities/enrollment_automations/README.md * rename delete-a-user-identity * rename create-a-user-identity * add_acs_user * update-noise-threshold * create-noise-threshold * rename noise thresholds * unlock-a-lock * locks * list-locks * get-lock * list-events * get-an-event * update-device * update-unmanaged-device * list-unmanaged-device * list-device-providers * list-devices * list-devices * get-device-1 * delete-device * list-connected-accounts * get-a-connected-account * delete-a-connected-account * connected_accounts/README.md * list-connect-webview * get-a-connect-webview * delete-a-connect-webview * create-a-connect-webview * connect_webviews * list-client-sessions * grant-access-to-a-client-session * get-or-create-a-client-session * get-a-client-session * delete-a-client-session * client_sessions * action_attempts * uesrs * systems * list-credentials-with-access-to-an-entrance * list-entrances * get-an-entrance * entrances * update-a-credential * unassign-a-credential-from-a-user * list-accessible-entrances * list-credentials * get-credential * delete-credential * create-credential-for-user * assign-a-credential-to-a-user * credentials * list-users-in-access-group * list-access-groups * get-access-group * access_groups * acs * update-an-access-code * list-unmanaged-access-codes * delete-an-unmanaged-access-code * convert-an-unmanaged-access-code * pull-backup-access-code * list-access-codes * get-an-access-code * delete-an-access-code * create-many-access-codes * create-many-access-codes * access_codes * access-control-systems * acs /client-sessions * /connect-webviews * connected_accounts * noise-sensors * docs/api-clients/acs/access_groups/README.md * revert overview.md * Nest Noise Thresholds * Use generated docs for /acs/systems * Page templates improvements (#318) * Change property details order and add line break between type and format in api-route.hbs * Capitalize boolean type * Fix resource property deprecation message and format * Un-italicize return type, add line break btw type and required in api-reference.hbs * REmove italic text from api-reference.hbs * Make return type a heading parallel to request params in api-reference layout * Bump blueprint to 0.14.2 * ci: Generate docs * Add resource description * Remove type from api-route page, use capitalized format only * Add "Properties" header after resource name in api-route layout * Decrease all heading levels by one in api-route.hbs * Endpoints section includes only first paragraph from the endpoint description * Remove console log * Fix heading levels of events and endpoints sections in api-route.hbs * Move resource description after its name * Test adding a new line in the beginning of endpoint page to render h1 header * Test adding forward slash * Remove forward slash * All caps format if it's 'id' * Add property enum values * Fix line break syntax * Move enum values after description --------- Co-authored-by: Seam Bot <[email protected]> * Only generate relative links to files that exist (#320) * Adjust link targets * ci: Generate docs * Remove +1 in link path * ci: Generate docs * Update links to /acs/systems * Only generate relative links to files that exist * ci: Generate docs * Fix link back to README.md * ci: Generate docs * Include hash in link * Fix relative path --------- Co-authored-by: Seam Bot <[email protected]> * Add ruff to devcontainer * Install ruby standard to devcontainer * Add cargo to path * Add standardrb * Add php-cs-fixer * Add shfmt * Add Optional Requirements to README * Update blueprint with async call * Pass in formatCode * Format javascript and json with prettier * Format with ruff * Format php with prettier plugin * Format bash with shfmt * Fix type error * Install ruff for action * Add shfmt to action * Install standardrb in action * Check command exists before running * Update blueprint * ci: Generate docs * Update README.md with standardrb * Update blueprint * Always trim formatted code * ci: Generate docs * Remove ==== line in formatted ruby output * ci: Generate docs --------- Co-authored-by: Andrii <[email protected]> Co-authored-by: Seam Bot <[email protected]> Co-authored-by: Andrii <[email protected]> Co-authored-by: Mike Wu <[email protected]> Co-authored-by: Andrii Balitskyi <[email protected]>
seamapi · Aug 30, 2024 · ce1863f · ce1863f
1 parent 7020e66
commit ce1863f
Show file tree

Hide file tree

Showing 10 changed files with 417 additions and 33 deletions.
diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
@@ -2,9 +2,20 @@ ARG VARIANT="20"
 
 FROM mcr.microsoft.com/vscode/devcontainers/javascript-node:${VARIANT}
 
+RUN apt-get update
+
+RUN apt-get install -y php ruby ruby-dev
+RUN gem install standard -v 1.31.0
+
+RUN wget https://github.com/mvdan/sh/releases/download/v3.9.0/shfmt_v3.9.0_linux_amd64 -O shfmt \
+ && chmod a+x shfmt \
+ && mv shfmt /usr/local/bin/shfmt
+
 USER node
 WORKDIR /home/node
 
+RUN curl -LsSf https://astral.sh/ruff/0.6.3/install.sh | sh
+
 RUN mkdir -p .config/git \
  && echo ".vscode/*" >> .config/git/ignore \
  && echo "*.code-workspace" >> .config/git/ignore \

diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -12,6 +12,9 @@
     "EditorConfig.EditorConfig",
     "esbenp.prettier-vscode"
   ],
+  "remoteEnv": {
+    "PATH": "${containerEnv:PATH}:${localEnv:HOME}/.cargo/env"
+  },
   "postCreateCommand": "npm install",
   "remoteUser": "node"
 }
diff --git a/.github/workflows/generate.yml b/.github/workflows/generate.yml
@@ -31,6 +31,21 @@ jobs:
         uses: ./.github/actions/setup
         with:
           install_dependencies: 'false'
+      - name: Install ruff
+        run: |
+          curl -LsSf https://astral.sh/ruff/0.6.3/install.sh | sh
+          echo "$HOME/.cargo/env" >> $GITHUB_PATH
+      - name: Install shfmt
+        run: |
+          wget https://github.com/mvdan/sh/releases/download/v3.9.0/shfmt_v3.9.0_linux_amd64 -O shfmt
+          chmod a+x shfmt
+          mv shfmt /usr/local/bin/shfmt
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+      - name: Install standardrb
+        run: gem install standard -v 1.31.0
       - name: Normalize package-lock.json
         run: npm install
       - name: Generate docs

diff --git a/README.md b/README.md
@@ -117,6 +117,17 @@ $ npm install
 [npm]: https://www.npmjs.com/
 [nvm]: https://github.com/creationix/nvm
 
+### Optional Requirements
+
+These tools are using to format code during documentation generation.
+They are not required for local development:
+if they are not installed, the doc generation will simply skip the formatting step.
+GitHub actions will automatically ensure the formatting is applied for all pull requests.
+
+- [shfmt](https://github.com/mvdan/sh)
+- [ruff](https://github.com/astral-sh/ruff)
+- [standardrb](https://github.com/standardrb/standard)
+
 ## GitHub Actions
 
 _GitHub Actions should already be configured: this section is for reference only._

diff --git a/docs/api/acs/systems/list.md b/docs/api/acs/systems/list.md
@@ -14,12 +14,14 @@ response includes all access control systems connected to your workspace.
     {% tab title="JavaScript" %}
   ### Request
   ```javascript
-  await seam.acs.systems.list({"connected_account_id":"8d7e0b3a-b889-49a7-9164-4b71a0506a33"})
+  await seam.acs.systems.list({
+  connected_account_id: "8d7e0b3a-b889-49a7-9164-4b71a0506a33",
+});
   ```
 
   ### Response
   ```javascript
-  [{"acs_system_id":"8d7e0b3a-b889-49a7-9164-4b71a0506a33"}]
+  [{ acs_system_id: "8d7e0b3a-b889-49a7-9164-4b71a0506a33" }];
   ```
     {% endtab %}
     {% tab title="Python" %}
@@ -41,19 +43,21 @@ response includes all access control systems connected to your workspace.
 
   ### Response
   ```ruby
-  [<Seam::AcsSystems:0x00000
-acs_system_id="8d7e0b3a-b889-49a7-9164-4b71a0506a33">]
+  [{"acs_system_id" => "8d7e0b3a-b889-49a7-9164-4b71a0506a33"}]
   ```
     {% endtab %}
     {% tab title="PHP" %}
   ### Request
   ```php
-  $seam->acs->systems->list(connected_account_id:"8d7e0b3a-b889-49a7-9164-4b71a0506a33")
+  <?php
+$seam->acs->systems->list(
+    connected_account_id: "8d7e0b3a-b889-49a7-9164-4b71a0506a33"
+);
   ```
 
   ### Response
   ```php
-  [{"acs_system_id":"8d7e0b3a-b889-49a7-9164-4b71a0506a33"}]
+  [{ "acs_system_id": "8d7e0b3a-b889-49a7-9164-4b71a0506a33" }]
   ```
     {% endtab %}
     {% tab title="Seam CLI" %}
@@ -64,7 +68,7 @@ acs_system_id="8d7e0b3a-b889-49a7-9164-4b71a0506a33">]
 
   ### Response
   ```seam_cli
-  [{"acs_system_id":"8d7e0b3a-b889-49a7-9164-4b71a0506a33"}]
+  [{ "acs_system_id": "8d7e0b3a-b889-49a7-9164-4b71a0506a33" }]
   ```
     {% endtab %}
 {% endtabs %}