-
Notifications
You must be signed in to change notification settings - Fork 10
Description
The reference documentation published on learn.microsoft.com includes samples that are provided using docstrings in the code in of this repo. The document generation supports three different styles of doc strings
- reStructuredText (RST): https://docutils.sourceforge.io/rst.html
- NumPy Style Python Docstrings: https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html
- Google Style Python Docs strings: https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html#example-google
While all three are supported, for consistency only one style should be used within the repo.
In this repo there are samples within the doc strings that don't follow any of these.
For example: /libraries/microsoft-agents-a365-notifications/microsoft_agents_a365/notifications/agent_notification.py#L46C5-L73C8 has this docstring:
"""Handler for agent notifications from Microsoft 365 applications.
This class provides decorators for registering handlers that respond to notifications
from various Microsoft 365 channels and subchannels. It supports routing based on
channel ID, subchannel, and lifecycle events.
Args:
app: The application instance that will handle the routed notifications.
known_subchannels: Optional iterable of recognized subchannels. If None,
defaults to all values in the AgentSubChannel enum.
known_lifecycle_events: Optional iterable of recognized lifecycle events. If None,
defaults to all values in the AgentLifecycleEvent enum.
Example:
```python
from microsoft_agents.hosting import Application
from microsoft_agents_a365.notifications import AgentNotification
app = Application()
notifications = AgentNotification(app)
@notifications.on_email()
async def handle_email(context, state, notification):
email = notification.email
if email:
await context.send_activity(f"Received email: {email.id}")
```
"""The triple backtick code fences used within this example doesn't align with any of the supported styles and will cause unusable, garbled strings to be published rather than the expected sample code.
Docstrings included in this repo should:
- Use one of the supported docstring styles consistently
- Update samples within those doc strings to remove the triple backtick code fences and align with the common style used.