Azure / Azure/azure-sdk-for-python

[docs] Fix documentation inconsistencies in doc/ folder

Open
#47,739 0 comments 0 reactions 0 assignees View on GitHub
agentic-workflows automated documentation
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.