Condensed api ref layout #596

mikewuu · 2025-05-16T03:45:29Z

Closes https://linear.app/seam/issue/CX-318/condensed-layout-for-docs

Implements the changes made in #548 based off latest main

mikewuu · 2025-05-16T03:46:57Z

@DebbieAtSeam, I tried my best copy changes from the diff in #548 . Some of the files have been updated significantly so I had to make changes by hand.

Hopefully I didn't break anything 🤞

DebbieAtSeam · 2025-05-16T16:34:15Z

Looks excellent! Thanks so much! Some comments:

One of us needs to move the table of contents entries around to match what's in Condense api ref layout #548. It's alpha.
Need a line break here, and format, etc. should go on the same line as the prop name (like the top-level props).
Nested enum lists need HTML formatting (I think HTML vs. MD is how we got it to work.).
Something needs to be fixed with this bulleted list of child props.
Something seems to be missing in endpoint request params.
Is it possible to add a horizontal line between code example blocks when there are multiple code examples?
Thanks!

mikewuu · 2025-05-21T02:36:10Z

docs/SUMMARY.md

@@ -3,7 +3,6 @@
 * [Seam Documentation](README.md)
 * [🚲 Quick Start](quickstart.md)
 * [🚀 Go Live!](go-live.md)
-* [Contact Us](contact-us.md)


One of us needs to move the table of contents entries around to match what's in #548. It's alpha.

@DebbieAtSeam, copied over the docs summary in b635346, is there anything else required for this?

mikewuu · 2025-05-21T03:04:51Z

src/layouts/partials/property-non-collapsible.hbs

@@ -1,5 +1,4 @@
-**`{{name}}`**
-Format: `{{format}}`{{#if listItemFormat}}, Item format: `{{listItemFormat}}`{{/if}}
+**`{{name}}`** Format: `{{format}}`{{#if listItemFormat}}, Item format: `{{listItemFormat}}`{{/if}}


Need a line break here, and format, etc. should go on the same line as the prop name (like the top-level props).

Updated in f55da16

mikewuu · 2025-05-21T03:27:58Z

src/layouts/partials/api-resource.hbs

+<details>
+<summary>Enum values</summary>
+{{#each enumValues}}
+- <code>{{this}}</code>


Nested enum lists need HTML formatting (I think HTML vs. MD is how we got it to work.).

Updated to use <code> instead in 8625455

mikewuu · 2025-05-21T03:33:25Z

src/layouts/partials/api-resource.hbs


-{{/each}}
+  {{#each objectProperties}}


Something needs to be fixed with this bulleted list of child props.

Fixed in 52fb020, just needed an extra line

mikewuu · 2025-05-21T03:37:19Z

src/layouts/api-endpoint.hbs

-Item format: `{{this.itemFormat}}`
-{{/if}}
-Required: {{#if this.required}}Yes{{else}}No{{/if}}
+**`{{this.name}}`** {{#if this.jsonType}}*{{this.jsonType}}*{{/if}}{{#if this.itemFormat}} *of {{this.itemFormat}}s*{{/if}}{{#if this.required}} (Required){{/if}}


Something seems to be missing in endpoint request params.

Fixed in 9e96cc8. Was due to certain params not having a jsonType defined.

mikewuu · 2025-05-21T03:54:41Z

src/layouts/api-endpoint.hbs


 {{#each additionalCodeSamples}}
+---


Is it possible to add a horizontal line between code example blocks when there are multiple code examples?

Yep, updated in b578dd1

See /docs/api/acs/users/create.md > Create a new ACS User for an example.

DebbieAtSeam · 2025-05-21T04:14:23Z

Many thanks, @mikewuu! Found just a couple more things...

Could the format of these child props please match the way it's rendered for higher-level props?
Just realized that we have errors and warnings twice on the resource pages. Only the top version has the props though. Let's ask @razor-x what he thinks. Is it superfluous to have them in both places? Which place (or both) should have the props?
it looks like some child props are being rendered as bulleted lists and some as horizontal line-separated lists with no bullets. Let's pick one and use it throughout. I think I prefer the hr-separated lists with no bullets, but I'm not totally sure.

Thanks!

razor-x · 2025-05-21T20:17:22Z

@DebbieAtSeam @mikewuu This PR is quite large now and has been open for a week. Please consider if any of the feedback or changes are blocking or not. If the current PR changes overall improve the docs, we can merge this and still fix the other items as a follow up :)

mikewuu · 2025-05-22T08:51:13Z

Could the format of these child props please match the way it's rendered for higher-level props?

@DebbieAtSeam do you mean to have it in italics?

mikewuu · 2025-05-22T08:53:15Z

@DebbieAtSeam @mikewuu This PR is quite large now and has been open for a week. Please consider if any of the feedback or changes are blocking or not. If the current PR changes overall improve the docs, we can merge this and still fix the other items as a follow up :)

@DebbieAtSeam should we just merge this now, and I'll open new PRs immediately for the new points in #596 (comment), to make the review easier?

DebbieAtSeam · 2025-05-22T11:34:59Z

Sure, you can merge it. I would like it if we could fix the last two remaining things in a follow up PR though. Thanks!

andrii-balitskyi · 2025-05-28T13:23:49Z

src/layouts/partials/property-content.hbs

+<details>
+    <summary>Enum values:</summary>

-{{> enum-values}}
+    {{#each enumValues}}
+    - <code>{{this}}</code>
+    {{/each}}
+</details>


@mikewuu Gitbook can't render nested details tags, so we can't use the tag here because it's used in property-collapsible partial which also uses details tag.

This property-content partial is also used in property-non-collapsible which you used in api-resource partial which also uses details tag

so are we good to just remove it from here?

I think so, something similar was implemented previously with the enum-values partial

thanks! Updated in #613

mikewuu and others added 14 commits May 15, 2025 23:00

add separate ACS User Create code sample

792ca26

update src/data/paths.yml add /access_codes paths

a58b3be

update api-endpoint.hbs

6b39f67

update layouts/api-namespace.hbs

d8b593c

update layouts/api-route.hbs

c32ad25

update partials/api-resource.hbs

7d76fd9

add api-response-resource.hbs

ae7ab5f

update code-sample.hbs

3a9fb16

update property-collapsible.hbs

2b47ac7

update property-content.hbs

a965fdc

update property-nested-internal

44a46d7

update property-nested.hbs

c6677dd

update reference.ts

aea715b

ci: Generate docs

3575dd2

mikewuu requested review from a team as code owners May 16, 2025 03:45

mikewuu and others added 2 commits May 16, 2025 12:54

update api-route.ts

19ef8c2

ci: Generate docs

d9a90d2

mikewuu and others added 4 commits May 21, 2025 11:19

Merge branch 'main' into condensed-api-v2

d67e7a5

ci: Generate docs

6148ea7

update docs/SUMMARY.md

b635346

fix property-non-collapsible linebreak singleline

f55da16

mikewuu force-pushed the condensed-api-v2 branch from a9e0656 to f55da16 Compare May 21, 2025 02:45

update enum lists to use <code> instead of ` ticks

8625455

mikewuu force-pushed the condensed-api-v2 branch from 64cd838 to 8625455 Compare May 21, 2025 03:26

seambot and others added 3 commits May 21, 2025 03:27

ci: Generate docs

6d58d27

fix bullet list incorrect formatting

52fb020

ci: Generate docs

8afc164

mikewuu and others added 4 commits May 21, 2025 12:36

fix extraneous ** in Request Parameters

9e96cc8

ci: Generate docs

e134e27

add --- between additional code samples

b578dd1

ci: Generate docs

cb71ce6

mikewuu commented May 21, 2025

View reviewed changes

mikewuu requested a review from DebbieAtSeam May 21, 2025 03:55

razor-x merged commit 9dc2287 into main May 22, 2025
14 checks passed

razor-x deleted the condensed-api-v2 branch May 22, 2025 17:13

This was referenced May 23, 2025

fix: make property names italics #607

Merged

fix: separate properties with --- #608

Merged

andrii-balitskyi reviewed May 28, 2025

View reviewed changes

mikewuu mentioned this pull request May 29, 2025

fix: broken nested details for enums #613

Merged

Condensed api ref layout #596

Condensed api ref layout #596

Uh oh!

Conversation

mikewuu commented May 16, 2025

Uh oh!

mikewuu commented May 16, 2025

Uh oh!

DebbieAtSeam commented May 16, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DebbieAtSeam commented May 21, 2025

Uh oh!

razor-x commented May 21, 2025

Uh oh!

mikewuu commented May 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mikewuu commented May 22, 2025

Uh oh!

DebbieAtSeam commented May 22, 2025

Uh oh!

Uh oh!

andrii-balitskyi May 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

andrii-balitskyi May 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mikewuu commented May 22, 2025 •

edited

Loading

andrii-balitskyi May 28, 2025 •

edited

Loading

andrii-balitskyi May 28, 2025 •

edited

Loading