request/response type clarity (README)

Author: mmacy

README.md

@@ -170,95 +170,11 @@ We recommend you *avoid* using this module-level client your application code be
 - It's harder to mock for testing purposes.
 - It's impossible to control cleanup of network connections.
 
-## Using types
+## Request types
 
-Nested request parameters are [TypedDicts][typing.TypedDict]. Responses are [Pydantic models](https://docs.pydantic.dev), which provide helper methods for things like:
+Nested **request** parameters are Python [TypedDicts][typing.TypedDict].
 
-- Serializing back into JSON: [`model.model_dump_json`][src.openai.BaseModel.model_dump_json]`(indent=2, exclude_unset=True)`
-- Converting to a dictionary: [`model.model_dump`][src.openai.BaseModel.model_dump_json]`(exclude_unset=True)`
-
-### Enable type checking in Visual Studio Code
-
-Typed requests and responses provide autocomplete and documentation in your editor.
-
-To help catch bugs earlier, enable [type checking in Pylance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance) in VS Code by setting `python.analysis.typeCheckingMode` to `basic` as described in **Settings and Customization** on the Marketplace page for Pylance.
-
-## Pagination
-
-List methods in the OpenAI API are paginated and Python library provides auto-paginating iterators on list responses - you don't need to request manually request successive pages.
-
-This example shows using auto-pagination when [listing fine tuning jobs][src.openai.resources.fine_tuning.Jobs.list]:
-
-```python
-import openai
-
-client = OpenAI()
-
-all_jobs = []
-# Automatically fetches more pages as needed.
-for job in client.fine_tuning.jobs.list(
-    limit=20,
-):
-    # Do something with job here
-    all_jobs.append(job)
-print(all_jobs)
-```
-
-Auto-pagination is also supported when [listing asynchrous fine tuning jobs][src.openai.resources.fine_tuning.AsyncJobs.list]:
-
-```python
-import asyncio
-import openai
-
-client = AsyncOpenAI()
-
-
-async def main() -> None:
-    all_jobs = []
-    # Iterate through items across all pages, issuing requests as needed.
-    async for job in client.fine_tuning.jobs.list(
-        limit=20,
-    ):
-        all_jobs.append(job)
-    print(all_jobs)
-
-
-asyncio.run(main())
-```
-
-### Manual pagination
-
-For more granular control of pagination, you can instead choose to use the `.has_next_page()`, [`.next_page_info()`][src.openai.pagination.SyncCursorPage.next_page_info], or `.get_next_page()` methods:
-
-```python
-first_page = await client.fine_tuning.jobs.list(
-    limit=20,
-)
-if first_page.has_next_page():
-    print(f"will fetch next page using these details: {first_page.next_page_info()}")
-    next_page = await first_page.get_next_page()
-    print(f"number of items we just fetched: {len(next_page.data)}")
-
-# Remove `await` for non-async usage.
-```
-
-Or, you can work directly with the data returned:
-
-```python
-first_page = await client.fine_tuning.jobs.list(
-    limit=20,
-)
-
-print(f"next page cursor: {first_page.after}")  # => "next page cursor: ..."
-for job in first_page.data:
-    print(job.id)
-
-# Remove `await` for non-async usage.
-```
-
-## Nested params
-
-Nested parameters are dictionaries, typed using [TypedDict][typing.TypedDict], for example:
+For example, the user message in the following [`chat.completions.create()`][src.openai.resources.chat.completions.Completions.create] request is a [`ChatCompletionUserMessageParam`][src.openai.types.chat.chat_completion_user_message_param.ChatCompletionUserMessageParam], which has a base type of [`TypedDict`][typing.TypedDict]:
 
 ```python
 from openai import OpenAI
@@ -269,17 +185,17 @@ completion = client.chat.completions.create(
     messages=[
         {
             "role": "user",
-            "content": "Can you generate an example json object describing a fruit?",
+            "content": "Can you generate an example JSON object describing a fruit?",
         }
     ],
     model="gpt-3.5-turbo-1106",
     response_format={"type": "json_object"},
 )
 ```
 
-## File uploads
+### File upload request types
 
-Request parameters that correspond to file uploads can be passed as `bytes`, a [`PathLike`][os.PathLike] instance or a tuple of `(filename, contents, media type)`.
+Request parameters that correspond to file uploads can be passed as [`bytes`][bytes], a [`PathLike`][os.PathLike] instance, or a tuple of `(filename, contents, media type)`.
 
 ```python
 from pathlib import Path
@@ -293,7 +209,18 @@ client.files.create(
 )
 ```
 
-The async client uses the exact same interface. If you pass a [`PathLike`][os.PathLike] instance, the file contents will be read asynchronously automatically.
+The async client uses the same interface. If you pass a [`PathLike`][os.PathLike] instance, the file contents will be read asynchronously automatically.
+
+## Response types
+
+**Responses** are [Pydantic](https://docs.pydantic.dev) models that include their helper methods for things like:
+
+- Serializing the object to JSON: [`example_response_object.model_dump_json`][src.openai.BaseModel.model_dump_json]`(indent=2, exclude_unset=True)`
+- Converting the object to a dictionary: [`example_response_object.model_dump`][src.openai.BaseModel.model_dump]`(exclude_unset=True)`
+
+!!! Tip
+
+    Typed requests and responses enable type checking, autocompletion, and hover-help documentation in editors that support those features. In Visual Studio Code, for example, you can [enable type checking in Pylance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance) by setting `python.analysis.typeCheckingMode` to `basic` as described in that article's **Settings and Customization** section.
 
 ## Handling errors
 

docs/index.md

@@ -3,13 +3,13 @@
 Welcome to Marsh's totally unofficial and totally unsupported documentation for the OpenAI Python library.
 
 <div class="grid cards" markdown>
-- :fontawesome-brands-python: [OpenAI Python library reference](openai.md)
 - :material-clock-fast: [Get started with the library](./get_started.md)
+- :fontawesome-brands-python: [OpenAI Python library reference](openai.md)
 </div>
 
 ## About these docs
 
-The these docs are officially unofficial and unsupported, but you're welcome to use and improve them until OpenAI brings up their own set (1) or they ask me to take them down.
+These docs are officially unofficial and unsupported, but you're welcome to use and improve them until OpenAI brings up their own (1) or they ask me to take them down.
 { .annotate }
 
 1. I'll likely decommission this site when OpenAI [publishes their own Python API reference](https://community.openai.com/t/where-is-the-documentation-for-the-python-openai-sdk/583643).
@@ -22,14 +22,13 @@ You might instead prefer to use OpenAI's official docs on [OpenAI's official doc
 
 ### Unsupported
 
-**The documentation on this site is provided AS-IS and with NO WARRANTY.** The API reference on this site is generated from the OpenAI Python library's code, but I make no promises nor guarantee these docs reflect the current, past, or future state of the library.
+**The documentation on this site is provided AS-IS with NO WARRANTY.** The API reference is indeed generated from the OpenAI Python library's code, but I make no promises nor guarantee these docs reflect the current, past, or future state of the library.
 
-That said, I use these docs myself and thus intend to keep them (mostly) current, but there's no automation pulling content from their repo to this fork. (1)
+That said, I use these docs myself and thus intend to keep them (mostly) current. However, there's no automation pulling content from their repo to this fork. (1)
 { .annotate }
 
-1. This means you might encounter inaccuracies or you might not find what you think should be here. In either case, you should refer to [openai/openai-python](https://github.com/openai/openai-python) as the source of truth.
+1. That means you might encounter inaccuracies or you might not find what you think should be here. In either case, you should refer to [openai/openai-python](https://github.com/openai/openai-python) as the source of truth.
 
-___
 !!! quote
 
     If these docs help you, yay! If they don't, don't use 'em. Enjoy! *—[Marsh](https://github.com/mmacy)*

mkdocs-requirements.txt

@@ -6,6 +6,7 @@ click==8.1.7
 colorama==0.4.6
 ghp-import==2.1.0
 griffe==0.40.1
+griffe-inherited-docstrings==1.0.0
 idna==3.6
 Jinja2==3.1.3
 Markdown==3.5.2

mkdocs.yml

@@ -84,15 +84,17 @@ plugins:
               ignore_init_summary: true
             docstring_section_style: spacy
             docstring_style: google
+            extensions:
+              - griffe_inherited_docstrings
             filters: ["!^_"]
             heading_level: 3
             inherited_members: false
             merge_init_into_class: true
             separate_signature: true
             show_bases: true
             show_if_no_docstring: true
-            show_root_heading: true
             show_root_full_path: false
+            show_root_heading: true
             show_signature_annotations: true
             show_source: false
             show_symbol_type_heading: true

scripts/gen_ref_nav.py

@@ -0,0 +1,36 @@
+"""Generate the code reference pages and navigation."""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+mod_symbol = '<code class="doc-symbol doc-symbol-nav doc-symbol-module"></code>'
+
+src = Path(__file__).parent.parent / "src"
+
+for path in sorted(src.rglob("*.py")):
+    module_path = path.relative_to(src).with_suffix("")
+    doc_path = path.relative_to(src / "mkdocstrings").with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
+
+    parts = tuple(module_path.parts)
+
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+    elif parts[-1].startswith("_"):
+        continue
+
+    nav_parts = [f"{mod_symbol} {part}" for part in parts]
+    nav[tuple(nav_parts)] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        ident = ".".join(parts)
+        fd.write(f"::: {ident}")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, ".." / path)
+
+with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())