能否让Sphinx Autodoc处理动态属性？Bravado客户端场景问询

Great question—Sphinx Autodoc has limited out-of-the-box support for dynamic properties generated via __getattr__, but there are practical workarounds and customizations you can implement to get it to document these properties properly. Here's how to approach it:

• Default Behavior: Autodoc Relies on Static Analysis
  By default, Sphinx Autodoc looks for statically defined members in a class's __dict__ or via introspection of static attributes. Since your dynamic properties are created on-the-fly via __getattr__, they won't show up in standard Autodoc output unless you explicitly tell Sphinx about them.

• Leverage Your Custom __dir__ Method
  Since you've already overridden __dir__ to return the full list of dynamic properties matching your Swagger spec, you can build a small Sphinx extension to hook into Autodoc's processing. The extension can:

  1. When documenting your client class, call __dir__ on an instance (or the class itself, if your __dir__ is class-level) to fetch all dynamic properties.
  2. For each property in that list, generate a documentation entry, pulling in descriptions or details directly from your OpenAPI schema to populate meaningful docstrings.

• Use the autodoc-skip-member Event
  You can register a handler for Sphinx's autodoc-skip-member event to prevent Autodoc from skipping your dynamic properties. Here's a quick example you can add to your conf.py:

  def skip_dynamic_properties(app, what, name, obj, skip, options):
      # Replace `YourSwaggerClient` with your actual client class
      if what == "class" and name in YourSwaggerClient().__dir__():
          return False  # Don't skip this dynamic property
      return skip
  
  def setup(app):
      app.connect('autodoc-skip-member', skip_dynamic_properties)
  

  To make this useful, ensure your dynamic properties have proper docstrings. When generating properties in __getattr__, set their __doc__ attribute using descriptions pulled from your OpenAPI spec (e.g., endpoint summaries or parameter details).

• Generate Static Stub Files (Most Reliable Approach)
  For the most robust solution, generate static stub files (.pyi) that mirror the structure of your dynamic client. You can use bravado-core to parse your OpenAPI spec and auto-generate these stubs, which include static definitions of all your endpoints and properties. Once you have these stubs, Sphinx Autodoc will treat them like regular Python code, automatically generating documentation without needing custom extensions.

In short: Yes, you can get Sphinx Autodoc to document your dynamic Bravado client properties—you just need to either customize Sphinx's behavior to recognize them or provide static stubs that give Autodoc the structure it expects.

内容的提问来源于stack exchange，提问作者user3761100