@activity.defn support and other minor things (#16)

Author: cretz

.gitignore

@@ -2,6 +2,7 @@
 __pycache__
 /build
 /dist
+/docs/_autosummary
 /docs/_build
 temporalio/api/*
 !temporalio/api/__init__.py

README.md

@@ -125,7 +125,9 @@ import asyncio
 import logging
 from temporalio.client import Client
 from temporalio.worker import Worker
+from temporalio import activity
 
+@activity.defn
 async def say_hello_activity(name: str) -> str:
     return f"Hello, {name}!"
 
@@ -135,7 +137,7 @@ async def main(stop_event: asyncio.Event):
   client = await Client.connect("http://localhost:7233", namespace="my-namespace")
 
   # Run the worker until the event is set
-  worker = Worker(client, task_queue="my-task-queue", activities={"say-hello-activity": say_hello_activity})
+  worker = Worker(client, task_queue="my-task-queue", activities=[say_hello_activity])
   async with worker:
     await stop_event.wait()
 ```
@@ -148,6 +150,7 @@ Some things to note about the above code:
 * Activities are passed as a mapping with the key as a string activity name and the value as a callable
 * While this example accepts a stop event and uses `async with`, `run()` and `shutdown()` may be used instead
 * Workers can have many more options not shown here (e.g. data converters and interceptors)
+* A custom name for the activity can be set with a decorator argument, e.g. `@activity.defn(name="my activity")`
 
 #### Types of Activities
 
@@ -276,4 +279,14 @@ The Python SDK is built to work with Python 3.7 and newer. It is built using
 
   ```bash
   poe test
-  ```
+  ```
+
+### Style
+
+* Mostly [Google Style Guide](https://google.github.io/styleguide/pyguide.html). Notable exceptions:
+  * We use [Black](https://github.com/psf/black) for formatting, so that takes precedence
+  * In tests and example code, can import individual classes/functions to make it more readable. Can also do this for
+    rarely in library code for some Python common items (e.g. `dataclass` or `partial`), but not allowed to do this for
+    any `temporalio` packages or any classes/functions that aren't clear when unqualified.
+  * We allow relative imports for private packages
+  * We allow `@staticmethod`

docs/_static/temporal-logo-dark-mode.svg

@@ -0,0 +1,20 @@
+
+{{ fullname | escape | underline}}
+===============
+
+.. automodule:: {{ fullname }}
+   :members:
+
+{% block modules %}
+{% if fullname != "temporalio.worker" %}
+{% if modules %}
+.. autosummary::
+   :toctree:
+   :template: custom_module_template.rst
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endif %}
+{% endblock %}

docs/_static/temporal-logo-light-mode.svg

@@ -30,6 +30,7 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
 ]
@@ -54,12 +55,18 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
+html_theme_options = {
+    "light_logo": "temporal-logo-light-mode.svg",
+    "dark_logo": "temporal-logo-dark-mode.svg",
+}
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
     "protobuf": ("https://googleapis.dev/python/protobuf/latest/", None),
 }
 
+html_title = "API Documentation"
+
 autodoc_docstring_signature = True
 
 autodoc_typehints = "description"
@@ -75,3 +82,5 @@
 autodoc_default_options = {
     "special-members": "__aenter__,__aexit__,__init__",
 }
+
+autosummary_generate = True

docs/_templates/custom_module_template.rst

@@ -1,22 +1,26 @@
-.. Temporal Python SDK documentation master file, created by
-   sphinx-quickstart on Fri Feb  4 11:52:42 2022.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
 
-Temporal Python SDK
-===================
+Temporal Python SDK API Documentation
+=====================================
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+Modules
+-------
 
-   api
-   direct_api
+.. autosummary::
+   :toctree: _autosummary
+   :template: custom_module_template.rst
+   :recursive:
 
+   temporalio.client
+   temporalio.worker
+   temporalio.activity
+   temporalio.converter
+   temporalio.exceptions
+   temporalio.api
+   temporalio.workflow_service
 
 
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
 * :ref:`modindex`