[Feature Request]: Improve Python state docs

[damccorm]

What would you like to happen?

It is unclear how to use some state from the pydoc. For example, searching for BagState yields BagStateSpec only: https://beam.apache.org/releases/pydoc/2.62.0/search.html?q=BagState&check_keywords=yes&area=default

We have more info here - https://beam.apache.org/documentation/programming-guide/#state-and-timers - but the actual pydocs are unclear. We should link to the programming guide from the pydoc for different state specs and StateDoFnParam

Issue Priority

Priority: 2 (default / most feature requests should be filed as P2)

Issue Components

• Component: Python SDK
• Component: Java SDK
• Component: Go SDK
• Component: Typescript SDK
• Component: IO connector
• Component: Beam YAML
• Component: Beam examples
• Component: Beam playground
• Component: Beam katas
• Component: Website
• Component: Infrastructure
• Component: Spark Runner
• Component: Flink Runner
• Component: Samza Runner
• Component: Twister2 Runner
• Component: Hazelcast Jet Runner
• Component: Google Cloud Dataflow Runner

[rakeshcusat]

@damccorm I am happy to take care of this. Let's decide what is the primary source of truth that we are going to treat moving forward?

Is it Pydoc? or programming-guide?

I would vote for the pydoc since that is closer to the code and easier to maintain. what do you think?

[damccorm]

IMO programming guide is probably better because we have several different kinds of state, so if we make pydoc the source of truth we'd have to replicate the broader state documentation across all of them (as opposed to just having a small snippet about that particular kind of state and a link to the programming guide).

[rakeshcusat]

@damccorm make sense, I can take a first stab at it. I had also noticed that the programming guide is missing some state. I had sent some PR in past but I don't think it is still there where we want it to be. There are so many minor utility functionality added to the state those are not documented anywhere.
I think I should take this opportunity to just update the various documentations.

[rakeshcusat]

.take-issue

[github-actions]

This issue has been marked as stale due to 150 days of inactivity. It will be closed in 30 days if no further activity occurs. If you think that’s incorrect or this issue still needs to be addressed, please simply write any comment. If closed, you can reopen the issue at any time. Thank you for your contributions.