Azure / Azure/azure-sdk-for-python
[docs] Fix documentation inconsistencies in doc/ folder
- Dominant language
- Python
- Stars
- 5.6k
- Forks
- 3.4k
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 193
Description
This PR fixes several documentation inconsistencies found by cross-referencing `doc/` markdown files against the actual source code and repository structure.
## Changes
### `doc/request_builders.md` and `doc/send_request.md`
**Bug: `raise_for_error()` → `raise_for_status()`** — Both files' Troubleshooting sections referenced a non-existent `.raise_for_error()` method. The correct method is `.raise_for_status()` (verified in `sdk/core/azure-core/azure/core/rest/_rest_py3.py` line 310).
**Bug: `with` → `async with` in async examples** — The async code examples used synchronous context manager syntax (`with DefaultAzureCredential() ... with ExampleClient(...)`) where `async with` is required. Azure SDK async clients implement `__aenter__`/`__aexit__`.
**Bug in `request_builders.md`: wrong import** — `from azure.example.core.rest import HttpRequest` should be `from azure.core.rest import HttpRequest`.
**Bug in `request_builders.md`: `response.text` → `response.text()`** — `text` is a method on `HttpResponse`, not a property (verified in `sdk/core/azure-core/azure/core/rest/_rest_py3.py` line 291).
### `doc/dev/docstring.md`
**Inconsistency: comment-style type hint** — The code example showed a Python 2-era comment-style type hint (`# type: (str, bool, Any) -> LROPoller[CustomFormModel]`), which directly contradicts the guidance in `doc/dev/static_type_checking.md` ("Do not use comment style type hints"). Updated to annotation-style inline type hints.
### `doc/dev/mgmt/mgmt_release.md`
**Wrong filename: `version.py` → `_version.py`** — The file referenced `azure/mgmt/myservice/version.py` but all modern management packages use `_version.py` (with leading underscore). Verified by `find sdk/ -path "*/azure/mgmt/*/_version.py"` returning many results versus only one legacy package using `version.py`.
### `doc/dev/package_version/package_version_rule.md`
**Wrong GitHub org in URL** — Link used `github.com/azure-sdk/azure-sdk-for-python` (wrong organization) instead of `github.com/Azure/azure-sdk-for-python`.
### `doc/dev/tests.md`
**Stale links: Key Vault `test-resources.json` → `test-resources.bicep`** — Three reference links pointed to Key Vault's `test-resources.json` at a historical commit hash. Key Vault has since migrated to `test-resources.bicep` (the `.json` file no longer exists on the main branch). Updated all three links to point to the current `.bicep` file on `main`:
- Main file link → `test-resources.bicep`
- Resources section example → `test-resources.bicep#L38` (first `resource` block)
- Outputs section example → `test-resources.bicep#L174` (first `output` declaration)
> Generated by [Documentation Consistency Check](https://github.com/Azure/azure-sdk-for-python/actions/runs/28352537434) · 2.3K AIC · ⌖ 18 AIC · ⊞ 32.4K · [◷](https://github.com/search?q=repo%3AAzure%2Fazure-sdk-for-python+%22gh-aw-workflow-id%3A+doc-consistency-check%22&type=pullrequests)
---
> [!NOTE]
> This was originally intended as a pull request, but GitHub Actions is not permitted to create or approve pull requests in this repository.
> The changes have been pushed to branch `doc/consistency-fixes-2025-6c01f3db7be0297f`.
>
> **[Click here to create the pull request](https://github.com/Azure/azure-sdk-for-python/compare/main...doc/consistency-fixes-2025-6c01f3db7be0297f?expand=1&title=%5Bdocs%5D%20Fix%20documentation%20inconsistencies%20in%20doc%2F%20folder)**
To fix the permissions issue, go to **Settings** → **Actions** → **General** and enable **Allow GitHub Actions to create and approve pull requests**. See also: [gh-aw FAQ](https://github.github.com/gh-aw/reference/faq/#why-is-my-create-pull-request-workflow-failing-with-github-actions-is-not-permitted-to-create-or-approve-pull-requests)
Show patch preview (161 of 161 lines)
```diff
From 0fabce02ac455478c8c7f873a362ecc3662bb5c2 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
Date: Mon, 29 Jun 2026 06:29:54 +0000
Subject: [PATCH] doc: fix inconsistencies in documentation files
- request_builders.md, send_request.md: fix async context manager syntax
(with -> async with) in async code examples
- request_builders.md, send_request.md: fix wrong method name raise_for_error()
-> raise_for_status()
- request_builders.md: fix wrong import 'azure.example.core.rest' -> 'azure.core.rest'
- request_builders.md: fix response.text (property) -> response.text() (method call)
- doc/dev/docstring.md: replace legacy comment-style type hint with annotation-style
type hints, consistent with static_type_checking.md guidance
- doc/dev/mgmt/mgmt_release.md: fix version file path version.py -> _version.py
- doc/dev/package_version/package_version_rule.md: fix wrong GitHub org in URL
(azure-sdk -> Azure)
- doc/dev/tests.md: update Key Vault test-resources links from deleted .json file
at historical commit to current test-resources.bicep on main branch
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
doc/dev/docstring.md | 8 ++++++--
doc/dev/mgmt/mgmt_release.md | 2 +-
doc/dev/package_version/package_version_rule.md | 2 +-
doc/dev/tests.md | 6 +++---
doc/request_builders.md | 10 +++++-----
doc/send_request.md | 6 +++---
6 files changed, 19 insertions(+), 15 deletions(-)
diff --git a/doc/dev/docstring.md b/doc/dev/docstring.md
index 876c67c7..c9b7a67f 100644
--- a/doc/dev/docstring.md
+++ b/doc/dev/docstring.md
@@ -16,8 +16,12 @@ Docstrings are noted by the Python long-string `""""""`. When adding
A method docstring is annotated by the Python long-string `""""""` right after the method definition. The convention is a short
... (truncated)
```
Contributor guide
Research direction
Review the six listed files under doc/, starting with doc/request_builders.md and doc/send_request.md, and compare each example or link with the referenced source files and repository paths. Done means all named method, syntax, import, filename, URL, and Key Vault link inconsistencies are corrected; the issue notes that changes already exist on branch doc/consistency-fixes-2025-6c01f3db7be0297f.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 15/100