Azure / Azure/azure-sdk-for-python

[docs] Fix documentation inconsistencies in doc/ folder

Open
#48,272 1 comment 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

## 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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.