docs: Update documentation #146

gismya · 2023-09-15T00:06:31Z

I have added automatic tests where applicable
The PR title is suitable as a release note
The PR contains a description of what has been changed
The description contains manual test instructions

Changes

Starts chipping away at #100. Mostly moving the old RTD documentations to markdown and making sure it's referencing modern development workflow and current features in the client. An amalgamation of the old documentation, the python documentation, the work that @jimmycallin did in an older branch and some newly written things.

Test

Would be great if anyone could check the code examples for issues.

…eadme

ffMathy

This is amazing! Great work. Can't wait for this to be out so we can more easily contribute to the documentation too.

Minor comments.

README.md

ffMathy · 2023-09-15T04:48:26Z

README.md

+
+### Error handling
+
+A lot of the methods involve promises that might not always be resolved for various reasons. The examples will not have any error handling to keep them short, but make sure you have proper error handling when using the `EventHub`.


For the promises that don't resolve. Is it possible to introduce a sane default timeout? I guess it's not for this issue. Just food for thought.

For event publish, there is a timeout option that defaults to 30 seconds.

ffMathy · 2023-09-15T04:51:50Z

README.md

+
+When handling an event it is sometimes useful to be able to send information back to the source of the event. For example, `ftrack.location.request-resolve` would expect a resolved path to be sent back.
+
+You can craft a custom reply event if you want, but an easier way is just to return the appropriate data from your handler. Any value different from *null* or *undefined* will be automatically sent as a reply:


I'd love a note here referencing the fact that this implicitly uses the publishReply function (described further down).

I personally missed this the first time reading the documentation, and it lead me to believe that it was only possible to respond to events synchronously directly in the callback.

We actually don't describe publishReply currently. I don't know enough about what a believable example would be to write that section, but I've added a short mention of publishReply here.

ffMathy · 2023-09-15T04:54:01Z

README.md

+
+#### Subscription expressions
+
+The JavaScript API currently only support expressions on the format `topic=value` including wildcard support `topic=ftrack.*`, and more complex expressions such as filtering based on event source or data are not supported.


Is this true? Wasn't wildcard support added recently? I believe at least subscribing to all events is possible. We are doing that now.

The more complex expressions, like filtering on source are still not supported.

Yes, wildcards is explicitly stated as supported. If the wording is confusing, please suggest an alternate wording.

Ah. I misread it lol. It's actually really clear. Just a brain fart.

ffMathy · 2023-09-15T04:54:52Z

README.md

+#### Target expression
+
+Targeted events will invoke all subscribers of the topic, not just those
+matching the target expression-


Should be a period instead of a dash at the end here.

ffMathy · 2023-09-15T04:56:08Z

README.md

+session.eventHub.publishAndWaitForReply(event, { timeout: 5 }).then(onReply, onError);
+```
+
+### Limitations


I think all of these limitations should have issues created for them. Would make it easier for us to contribute with fixes.

README.md

lucaas

Nice work! Feel free to merge as-is or address comments first as you wish.

We will iterate on this, but need some basic info in place in the meantime.

README.md

lucaas · 2023-09-15T06:57:12Z

README.md

+
+#### Subscription expressions
+
+The JavaScript API currently only support expressions on the format `topic=value` including wildcard support `topic=ftrack.*`, and more complex expressions such as filtering based on event source or data are not supported.


The more complex expressions, like filtering on source are still not supported.

lucaas · 2023-09-15T07:59:15Z

README.md

+
+### Error handling
+
+A lot of the methods involve promises that might not always be resolved for various reasons. The examples will not have any error handling to keep them short, but make sure you have proper error handling when using the `EventHub`.


For event publish, there is a timeout option that defaults to 30 seconds.

jimmycallin

Sweet!

Found one more file we can remove: MANIFEST.in

We should redirect the old documentation URL to this repository as well.

gismya · 2023-09-15T11:34:33Z

We should redirect the old documentation URL to this repository as well.

Yes. @lucaas is on it.

gismya and others added 10 commits September 15, 2023 00:12

Update README.md

ed57d85

Update handling_events.rst

077d568

Update installing.rst

942c70d

Move doc files to archive folder

7734265

Readme change

c68f904

Create new eventhub documentation

f5097fb

Move eventhub documentation

62609d3

Rename heading

b42850e

Update README.md

85cc4ab

TOC

7d5ba66

gismya requested a review from a team as a code owner September 15, 2023 00:06

gismya added 2 commits September 15, 2023 02:10

Remove the old documentation since we now cover the majority in the r…

aac508b

…eadme

Remove references to the old documentation

0e8ec68

ffMathy approved these changes Sep 15, 2023

View reviewed changes

lucaas approved these changes Sep 15, 2023

View reviewed changes

gismya added 2 commits September 15, 2023 11:34

Addressing review comments

d93bc44

Minor adjustments

612c1b3

lucaas approved these changes Sep 15, 2023

View reviewed changes

gismya and others added 2 commits September 15, 2023 11:41

nit

444cd0b

Prettier formatting

5855766

jimmycallin reviewed Sep 15, 2023

View reviewed changes

Delete old docs file

990f457

gismya merged commit b1b745e into main Sep 15, 2023

gismya deleted the update-documentation branch September 15, 2023 11:34


		### Error handling

		A lot of the methods involve promises that might not always be resolved for various reasons. The examples will not have any error handling to keep them short, but make sure you have proper error handling when using the `EventHub`.


		When handling an event it is sometimes useful to be able to send information back to the source of the event. For example, `ftrack.location.request-resolve` would expect a resolved path to be sent back.

		You can craft a custom reply event if you want, but an easier way is just to return the appropriate data from your handler. Any value different from null or undefined will be automatically sent as a reply:


		#### Subscription expressions

		The JavaScript API currently only support expressions on the format `topic=value` including wildcard support `topic=ftrack.*`, and more complex expressions such as filtering based on event source or data are not supported.

docs: Update documentation #146

docs: Update documentation #146

Uh oh!

Conversation

gismya commented Sep 15, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Test

Uh oh!

ffMathy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

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!

Uh oh!

lucaas left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jimmycallin left a comment

Choose a reason for hiding this comment

Uh oh!

gismya commented Sep 15, 2023

Uh oh!

Uh oh!

gismya commented Sep 15, 2023 •

edited

Loading