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
## 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)
```
Contributor guide
Research direction
Review the listed files under doc/dev, doc/request_builders.md, and doc/send_request.md against the referenced source paths and current repository structure. Start with the examples and links called out in the issue, then verify that parameter names, build commands, historical guidance, package references, dates, and domains are accurate. Done means all documented inconsistencies are corrected without changing unrelated content.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 25/100