Add "wireframe" for generated event docs #454

DebbieAtSeam · 2024-12-11T19:13:38Z

No description provided.

docs/api/thermostats/README.md

razor-x · 2024-12-11T21:25:54Z

docs/api/thermostats/README.md

+Key of the [climate preset](../../capability-guides/thermostats/creating-and-managing-climate-presets) that was activated.
+</details>
+<details>
+<summary>is_fallback_climate_preset <code>boolean</code></summary>


GitBook does not seems to be rendering the links inside the blocks

Other things are not being rendered inside these expand/collapse blocks either. See https://docs.seam.co/latest/api/acs/systems#location for an example of "`" not rendering as code.

The details block is HTML, right? If so, do we need to use HTML tags inside to get it to render?

That renders the URL now, but the url is going to https://github.com/seamapi/docs/blob/main/docs/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds/README.md

Other things are not being rendered inside these expand/collapse blocks either. See docs.seam.co/latest/api/acs/systems#location for an example of "`" not rendering as code.

Sounds like a GitBook issue and we will need to add a markdown render step for content that is inside html tags.

razor-x · 2024-12-11T21:35:52Z

Overall looks good!

Just realized that GitBook does generate anchor links for each expandable section, so that's cool! (https://docs.seam.co/latest/~/revisions/TltbxcE7HlDD4UFMenCt/api/thermostats#temperature_celsius-number)
Not sure what to do about the markdown not rendering inside the blocks. Are the links malformed or do we need to try <a> tags?
How to deal with common event properties like event_id? Do we leave those out here and only document them on the Events page, or repeat them for each event, or?

DebbieAtSeam · 2024-12-11T21:38:15Z

Overall looks good!

Just realized that GitBook does generate anchor links for each expandable section, so that's cool! (https://docs.seam.co/latest/~/revisions/TltbxcE7HlDD4UFMenCt/api/thermostats#temperature_celsius-number)

Yay!

Not sure what to do about the markdown not rendering inside the blocks. Are the links malformed or do we need to try <a> tags?

Was wondering the same thing. Can we try HTML instead of MD inside these blocks?

How to deal with common event properties like event_id? Do we leave those out here and only document them on the Events page, or repeat them for each event, or?

I vote for repeating them for completeness if it's something that can be done programmatically/automatically.

DebbieAtSeam · 2024-12-12T01:39:45Z

docs/api/thermostats/README.md

+
+<details>
+<summary>method <code>enum</code></summary>
+Method used to adjust the thermostat manually. `seam` indicates that the Seam API, Seam CLI, or Seam Console was used to adjust the thermostat.


@razor-x OK, this seems inconsistent with the other page that has expand/collapse blocks, but using "``" or "" works here to format text as code.

DebbieAtSeam · 2024-12-12T01:40:40Z

docs/api/thermostats/README.md

+</details>
+<details>
+<summary>upper_limit_celsius <code>number</code></summary>
+Upper temperature limit, in °C, defined by the set <a href="https://docs.seam.co/latest/capability-guides/thermostats/setting-and-monitoring-temperature-thresholds">threshold</a>.


@razor-x As you saw, the relative URL does not work. Using the full/absolute URL here does not work either. What should we do?

DebbieAtSeam · 2024-12-12T23:04:11Z

@razor-x Given the GitBook limitations that we've found, what's the next step for this PR?

razor-x · 2024-12-12T23:22:37Z

If links are unable to render inside the expandable section, we only have two choices (unless we contact GitBook support and they make it work)

Replace the expandable sections with something else in this PR.
Strip out the urls inside these sections during the doc gen step. (Leave this PR as is)

DebbieAtSeam · 2024-12-12T23:25:28Z

If links are unable to render inside the expandable section, we only have two choices (unless we contact GitBook support and they make it work)

Replace the expandable sections with something else in this PR.

Strip out the urls inside these sections during the doc gen step. (Leave this PR as is)

@razor-x Of these choices, I vote for 2. If also like to see what happens if I add an expand/collapse with a link through the GitBook UI. I wonder if it works there.

docs/api/thermostats/README.md

DebbieAtSeam · 2024-12-17T22:38:21Z

@razor-x Of course, it works when added through the GitBook GUI... and it looks identical to what we added through GitHub (that did not work).
a5578c4#diff-0ad85fee1e305f0af27a1d00939ecb6f2d99cd122bfff916d873fc62a4cf6106R127

Working: https://docs.seam.co/latest/api/noise_sensors#events

DebbieAtSeam · 2024-12-18T22:48:23Z

Conclusions:

To get code-formatted text within summary blocks, you need to use <code></code>.
To get code-formatted text within details blocks, but outside of summary blocks, you can use backticks.
Leaving spaces between lines is very important for getting links within details blocks to render correctly.
For relative links, make sure to include the README.md part of the URL if the absolute URL does not end in a specific filename.

DebbieAtSeam · 2024-12-19T17:12:08Z

@razor-x What's the next step for this PR? Should we merge it, or should the generation template additions go in this PR too?

razor-x · 2024-12-20T18:48:40Z

We can't merge this one because it has to be owned by the generation. But this PR will be used as a reference to update the template to match this format.

DebbieAtSeam · 2025-01-07T16:40:06Z

@razor-x Should we close this PR now?

Update generate.yml

48656b5

DebbieAtSeam requested a review from a team as a code owner December 11, 2024 19:13

DebbieAtSeam marked this pull request as draft December 11, 2024 19:13

DebbieAtSeam added 2 commits December 11, 2024 16:10

Update README.md

d47f57d

Merge branch 'main' into event-wireframe

35ca329

DebbieAtSeam marked this pull request as ready for review December 11, 2024 21:11

DebbieAtSeam requested a review from a team as a code owner December 11, 2024 21:11

DebbieAtSeam requested review from razor-x and andrii-balitskyi December 11, 2024 21:11

razor-x reviewed Dec 11, 2024

View reviewed changes

docs/api/thermostats/README.md Outdated Show resolved Hide resolved

razor-x reviewed Dec 11, 2024

View reviewed changes

DebbieAtSeam added 2 commits December 11, 2024 16:54

Testing HTML code instead of MD in a couple of places

9086799

Update README.md

8bcfee3

DebbieAtSeam commented Dec 12, 2024

View reviewed changes

Merge branch 'main' into event-wireframe

0aa4a95

razor-x assigned DebbieAtSeam Dec 13, 2024

DebbieAtSeam commented Dec 17, 2024

View reviewed changes

Change event props to code formatted

7ff80f5

DebbieAtSeam added 5 commits December 18, 2024 16:43

Troubleshoot links

5be691c

Test backtick for code

c842a60

Merge branch 'main' into event-wireframe

96c7c78

Try increasing spacing

85c4f3e

Fix typo

3c983cf

DebbieAtSeam added 3 commits December 18, 2024 17:28

Troubleshoot links

e115eba

Fix links

abd695b

Fix link

f0b878a

DebbieAtSeam requested a review from razor-x December 18, 2024 22:48

Merge branch 'main' into event-wireframe

097a960

razor-x marked this pull request as draft December 20, 2024 18:47

razor-x mentioned this pull request Dec 31, 2024

Render events on route pages #307

Closed

razor-x closed this Jan 7, 2025

github-actions bot deleted the event-wireframe branch January 22, 2025 15:04

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add "wireframe" for generated event docs #454

Add "wireframe" for generated event docs #454

DebbieAtSeam commented Dec 11, 2024

razor-x Dec 11, 2024

DebbieAtSeam Dec 11, 2024

DebbieAtSeam Dec 11, 2024

razor-x Dec 11, 2024

razor-x Dec 11, 2024

razor-x commented Dec 11, 2024 •

edited

Loading

DebbieAtSeam commented Dec 11, 2024 •

edited by razor-x

Loading

DebbieAtSeam Dec 12, 2024

DebbieAtSeam Dec 12, 2024

DebbieAtSeam commented Dec 12, 2024

razor-x commented Dec 12, 2024 •

edited

Loading

DebbieAtSeam commented Dec 12, 2024

DebbieAtSeam commented Dec 17, 2024 •

edited

Loading

DebbieAtSeam commented Dec 18, 2024 •

edited

Loading

DebbieAtSeam commented Dec 19, 2024

razor-x commented Dec 20, 2024

DebbieAtSeam commented Jan 7, 2025

Add "wireframe" for generated event docs #454

Add "wireframe" for generated event docs #454

Conversation

DebbieAtSeam commented Dec 11, 2024

razor-x Dec 11, 2024

Choose a reason for hiding this comment

DebbieAtSeam Dec 11, 2024

Choose a reason for hiding this comment

DebbieAtSeam Dec 11, 2024

Choose a reason for hiding this comment

razor-x Dec 11, 2024

Choose a reason for hiding this comment

razor-x Dec 11, 2024

Choose a reason for hiding this comment

razor-x commented Dec 11, 2024 • edited Loading

DebbieAtSeam commented Dec 11, 2024 • edited by razor-x Loading

DebbieAtSeam Dec 12, 2024

Choose a reason for hiding this comment

DebbieAtSeam Dec 12, 2024

Choose a reason for hiding this comment

DebbieAtSeam commented Dec 12, 2024

razor-x commented Dec 12, 2024 • edited Loading

DebbieAtSeam commented Dec 12, 2024

DebbieAtSeam commented Dec 17, 2024 • edited Loading

DebbieAtSeam commented Dec 18, 2024 • edited Loading

DebbieAtSeam commented Dec 19, 2024

razor-x commented Dec 20, 2024

DebbieAtSeam commented Jan 7, 2025

razor-x commented Dec 11, 2024 •

edited

Loading

DebbieAtSeam commented Dec 11, 2024 •

edited by razor-x

Loading

razor-x commented Dec 12, 2024 •

edited

Loading

DebbieAtSeam commented Dec 17, 2024 •

edited

Loading

DebbieAtSeam commented Dec 18, 2024 •

edited

Loading