Azure / Azure/azure-sdk-for-python

[docs] Fix documentation inconsistencies in doc/ folder

Aperta
#47,739 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
agentic-workflows automated documentation
Lingua principale
Python
Stelle
5.6k
Fork
3.4k
Merge medio
2g
PR unite (30g)
217

Descrizione

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)
```

Guida per i contributori

Apri la guida per i contributori

Direzione di ricerca

Esamina i sei file elencati sotto doc/, iniziando da doc/request_builders.md e doc/send_request.md, e confronta ogni esempio o collegamento con i file sorgente e i percorsi del repository a cui fanno riferimento. Il lavoro è completato quando tutte le incoerenze indicate relative a metodi, sintassi, import, nomi di file, URL e collegamenti Key Vault sono state corrette; l’issue segnala che le modifiche esistono già sul branch doc/consistency-fixes-2025-6c01f3db7be0297f.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
python
Ambito
documentation
Tipo di issue
Documentazione
Difficoltà
2/5
Tempo stimato
1-3 ore
Stato di attività
Tranquilla
Chiarezza
Specificata chiaramente
Idoneità per principianti
15/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.