re initialize tutorial documentation -

[lfunderburk]

reference code in markdown from .py files

[codspeed-hq]

CodSpeed Performance Report

Merging #464 will not alter performance

_{Comparing guide-migration (50cd5eb) with main (d7763d3)}

Summary

✅ 6 untouched benchmarks

[davidselassie]

Thanks for working on this!

Because I have spent too much time fighting with Sphinx, I have a lot of little formatting suggestions to play into the capabilities provided by our Sphinx theme. I think we should use those instead of hand rolled HTML because it will allow us to more easily consistently change all of the formatting in the future via the theme if we need to.

I'd encourage you to read through the "Authoring" articles as part of the MyST docs (like "Admonitions", etc. in the sidebar), the "Content and Features" articles as part of the PyData Theme docs (like "Theme-specific Elements", etc. in the sidebar), and the Sphinx Design docs for all the kinds of structures and visual features that we have access to.

[davidselassie]

Suggested change

	event_time_config: EventClock = EventClock(
	event_time_config = EventClock(

I don't think this has to be annotated because it's the same type? Does mypy complain otherwise?

[lfunderburk]

yes, it complained

[davidselassie]

Huh. Not sure why. Fine.

[lfunderburk]

Hi @davidselassie will this be fixed when it's merged?

Added it literally as you suggested it

:substitutions:
$ pip install bytewax==|version|

[davidselassie]

will this be fixed when it's merged?

As in, will it show the correct released, version? Yes. The whole point is if someone is looking at pre-release docs they get a hint that this doesn't work with the current stable version of Bytewax. Or did you mean something else?

[lfunderburk]

As in, will it show the correct released, version? Yes

Cool! Yes, that's what I meant

Ok pr ready for re-review

[davidselassie]

Oops. Forgot that since this is the first "tutorial", we'll need to add the new template path pattern to secondary_sidebar_items in /docs/conf.py to get the right sidebar to show up. Could you change that file to this?

    "secondary_sidebar_items": {
        "api/**": ["page-toc"],
        "guide/**": ["page-toc", "edit-this-page"],
        "tutorials/**": ["page-toc", "edit-this-page"],
    },

There unfortunately isn't a nice way to get "API docs don't have edit this page but everything else does" with a fallback because the builder errors if there's overlap.

[davidselassie]

Should we xref to <project:#xref-installing> so if people want more details they can dive deeper?

[davidselassie]

Suggested change

	## Sessions are Per-User

The core purpose of this step is to break out the user ID as the key of the stream so that we calculate session windows per-user and not in some other way. I think it's important here to mention how state keys work and why they're needed very briefly in the body of this section.

[davidselassie]

This should be moved later after we've talked about the windowing steps and defining the sessions since we don't use it until calculating the metrics.

[davidselassie]

Similar to how we couched that the TestingSource is just to showcase how to conceptually get data into the dataflow, we should similarly say that inspect is an operator that lets us dump a stream of data to stdout for prototyping, but isn't actually what you'd use in a production setup.