Improve Python documentation

[bryfox]

This PR improves the documentation of the Python SDK.

Runtime improvements:

• Sets the module name on pyclasses, which sets __module__
  • This fixes the printed representation (e.g., <class 'foxglove.schemas.Color'> instead of <class 'builtins.Color'>)
  • Note this is set to the re-exported public module rather than the generated module
• Provides __repr__ for schema and channel instances (e.g. SceneUpdateChannel(topic='/boxes') instead of <foxglove.channels.SceneUpdaterChannel object at 0x103717190>)
• Adds docstrings to the root module definitions

Note

To support channel printing, this adds a public topic() getter on TypedChannel in core.

Other changes:

• Moves developer docs to CONTRIBUTING, and add more information to README (based on the Rust readme)
• Creates some initial standalone documentation using Sphinx
  • Loosely based on the Rust readme
• Renames examples/ws-demo.py to examples/live_visualization.py

[linear]

FG-10175 Produce initial documentation for initial python testers

[gasmith]

Is it stdio, necessarily? We're forwarding logs to the logging facility. Since that's more or less what a python user would expect, perhaps we simply call this enable_logging(level:str) and document it as such.

Out of curiosity... how does pyo3-log populate the name, pathname, and lineno in the LogRecords it generates?

[bryfox]

Good point. I'll update the description. Does enable_logging seem clearer than enable_log_forwarding? Might it be confused with log()ging? This is the internal module, so being verbose & explicit seems OK to me.

how does pyo3-log populate...

Good question; I'm not too familiar with it. ...Looks like it just uses information from the Rust log record directly (with some substitution in the name): https://github.com/vorner/pyo3-log/blob/835647f0baf76e0af28178f8a3a63df25849fdfb/src/lib.rs#L439-L440

[gasmith]

Good point. I'll update the description. Does enable_logging seem clearer than enable_log_forwarding? Might it be confused with log()ging? This is the internal module, so being verbose & explicit seems OK to me.

Right, my bad, I was referring to the actual #[pyfunction], which currently shares the same name. I think we should take "forwarding" out of the name, because from a user's perspective this is just a python library. They don't care about the fact that our extension is written in rust, or that some form of "forwarding" is required to port log messages across the boundary.

[bryfox]

This is in the _foxglove_py module, which end users shouldn't be importing from. I think it should still be documented, but I think it's OK to make this more aware of the internals. But for now I updated the names; easy to update later.

But I agree with you on the public API. The methods there are currently named verbose_on and verbose_off. (I'm not a fan of those names, but I think they were chosen for the reason above — to avoid confusion with log()). The docstrings there now say "enable/disable logging".

[gasmith]

"previously-registered channel"?