Azure / Azure/azure-sdk-for-python

[docs] Fix documentation inconsistencies in doc/ folder

Offen
#48,272 1 Kommentar 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
agentic-workflows automated documentation
Vorherrschende Sprache
Python
Sterne
5.6k
Forks
3.4k
Ø Merge
2 T. 2 Std.
Gemergte PRs (30 T.)
213

Beschreibung

## Summary

This PR fixes several inconsistencies found during a documentation consistency review of the `doc/` folder against the actual source code and repository structure.

---

### Changes

#### `doc/dev/mgmt/tests.md`

- **Fixed incorrect `ClientSecretCredential` parameters** (🔴 Breaking): The code example used `secret=` and `tenant=` which are not valid parameter names. Corrected to `client_secret=` and `tenant_id=` to match the actual [`ClientSecretCredential.__init__`](sdk/identity/azure-identity/azure/identity/_credentials/client_secret.py) signature.
- **Removed stale `testsettings_local.cfg` instructions**: The live/playback toggle via a local `.cfg` file is an undocumented legacy path. Instructions now point solely to `AZURE_TEST_RUN_LIVE`, which is the documented and preferred approach.
- **Removed reference to removed `scenario_tests` package**: The package no longer exists in the repo; the reference was vestigial and confusing.

#### `doc/dev/mgmt/generation.md`

- **Fixed deprecated `python setup.py bdist_wheel`**: `setup.py`-based builds are deprecated. Updated to `python -m build --wheel`.

#### `doc/dev/dataplane_generation.md`

- **Updated stale changelog example date**: Example date `2022-02-02` updated to `2025-07-01` to avoid misleading readers.

#### `doc/dev/packaging.md`

- **Marked Python 2 / `azure-nspkg` section as historical**: The section said `MUST include` a conditional dependency on `azure-nspkg` for Python 2. Python 2 support is dropped; this section is now clearly marked as historical and not a current requirement.

#### `doc/dev/tests.md`, `doc/dev/mgmt/tests.md`, `doc/dev/docstring.md`, `doc/request_builders.md`, `doc/send_request.md`

- **Replaced all `docs.microsoft.com` links with `learn.microsoft.com`**: Microsoft migrated all documentation to `learn.microsoft.com`. While old URLs redirect, the links should reflect the canonical current domain.

> Generated by [Documentation Consistency Check](https://github.com/Azure/azure-sdk-for-python/actions/runs/30241261692) · 210.2 AIC · ⌖ 13.9 AIC · ⊞ 5.8K · [◷](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/fix-inconsistencies-2026-07-a134f7c6643416f8`.
>
> **[Click here to create the pull request](https://github.com/Azure/azure-sdk-for-python/compare/main...doc/fix-inconsistencies-2026-07-a134f7c6643416f8?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 (249 of 249 lines)

```diff
From edc3dcb8248082798a724a08a5335633235f64ed Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
Date: Mon, 27 Jul 2026 06:07:45 +0000
Subject: [PATCH] doc: fix inconsistencies across doc/ folder

- Fix incorrect ClientSecretCredential parameters in mgmt/tests.md:
secret= -> client_secret=, tenant= -> tenant_id=
- Remove stale testsettings_local.cfg instructions (use AZURE_TEST_RUN_LIVE)
- Remove stale 'scenario_tests' package reference
- Fix deprecated 'python setup.py bdist_wheel' -> 'python -m build --wheel'
- Update stale changelog example date from 2022 to 2025
- Mark Python 2 / azure-nspkg section as historical (not a current requirement)
- Replace all docs.microsoft.com links with learn.microsoft.com

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
doc/dev/dataplane_generation.md | 2 +-
doc/dev/docstring.md | 4 ++--
doc/dev/mgmt/generation.md | 2 +-
doc/dev/mgmt/tests.md | 28 +++++++++-------------------
doc/dev/packaging.md | 8 +++++---
doc/dev/tests.md | 2 +-
doc/request_builders.md | 18 +++++++++---------
doc/send_request.md | 18 +++++++++---------
8 files changed, 37 insertions(+), 45 deletions(-)

diff --git a/doc/dev/dataplane_generation.md b/doc/dev/dataplane_generation.md
index 54161550..7f326b6f 100644
--- a/doc/dev/dataplane_generation.md
+++ b/doc/dev/dataplane_generation.md
@@ -175,6 +175,6 @@ If adding a new module group (new sub-folder under `sdk/`), add an entry to [COD

See the [Release Checklist](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/8/Release-Checklist?anchor=prepare-release-script). Before submitting a PR:

-- **Update CHANGELOG.md** with the changes for the new version and an approximate release date (e.g., `1.0.0b1 (2022-02-02)`).
+- **Update CHANGELOG.md** with the changes for the new version and an approximate release date (e.g., `1.0.0b1 (2025-0
... (truncated)
```

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Überprüfe die unter doc/dev aufgeführten Dateien sowie doc/request_builders.md und doc/send_request.md anhand der referenzierten Quellpfade und der aktuellen Repository-Struktur. Beginne mit den im Issue genannten Beispielen und Links und überprüfe anschließend, ob Parameternamen, Build-Befehle, historische Hinweise, Paketverweise, Daten und Domains korrekt sind. Erledigt ist die Aufgabe, wenn alle dokumentierten Inkonsistenzen korrigiert wurden, ohne nicht dazugehörige Inhalte zu ändern.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
python
Bereich
documentation
Issue-Typ
Dokumentation
Schwierigkeit
3/5
Geschätzter Aufwand
1-2 Tage
Aktivitätsstatus
Ruhig
Klarheit
Klar beschrieben
Anfängerfreundlichkeit
25/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.