Integrate auto-generated documentation for Gazebo Python bindings into the main docs site

[j-rivero]

Summary

Add auto-generated Python API documentation for Gazebo libraries with Python bindings, integrated into the main documentation site.

Motivation

Gazebo libraries increasingly provide Python bindings (sdformat, gz-math, gz-msgs, gz-transport), but there's no centralized API documentation for Python users. This makes it difficult for Python developers to discover and use the available APIs.

Context

It could follow the existing Doxygen (C++ API) documentation pattern:

1. Nightly CI workflow to build Python documentation using Sphinx autodoc
2. Automatic deployment to gazebosim.org/api/python/{library}/{version}/
3. Integration with main docs via Library Reference page links
4. Prototype with sdformat, then expand to other libraries

Technical Approach suggestions

• Use Sphinx with autodoc extension to generate documentation from installed Python modules
• Follow the existing nightly-upload.yml workflow pattern for C++ Doxygen docs
• Deploy to /api-python/ nested under the existing /api/ structure
• Build for each active distribution (Fortress, Harmonic, Ionic, Jetty)

[j-rivero]

A possible path for the implementation:

Step 1. Implement sphinx doc generation in gz-cmake

Similar to doxygen:

• Add GzCreatePythonDocs.cmake module
• Use existing BUILD_DOCS option (no new option needed)
• Provide shared Sphinx configuration templates

Step 2. Use a testing repository for integration

• We can use sdformat or gz-math
• See how the new gz-cmake call to BUILD_DOCS needs to be modified to inject extra information for sphinx.

Step 3. Integrate changes in the doc production workflow

• Add Sphinx to nightly build dependencies
• Collect and deploy Python docs to /api-python/ for the libraries that provides them

Step 4. Extend to all libraries + Docstring improvements in testing repository

• Implement the changes required in all the libraries that provides bindings
• Enhance existing pybind11 docstrings with parameter/return docs