Azure / Azure/azure-sdk-for-python

[docs] Fix documentation inconsistencies in doc/ folder

Open
#48,507 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

## Summary

This PR fixes a set of documentation inconsistencies found across the `doc/` folder by verifying every claim against the current repository state and tooling.

---

## Changes

### `doc/dev/dev_setup.md`
- **Fixed H1 title**: Was `# Run SDK tests` (wrong file name/purpose). Changed to `# Developer Setup` to match what the file is linked as in both READMEs.

### `doc/dev/tests.md`
- **Python 3.10 Windows Store link**: Updated from the old `microsoft.com/p/` format to the new `apps.microsoft.com/detail/` format (matching the already-updated 3.11 and 3.12 links on the same line).
- **Internal URL replaced**: `review.learn.microsoft.com` is Microsoft's internal content review portal, inaccessible to external contributors. Replaced with the public `learn.microsoft.com` equivalent.
- **Keyvault test-resources links**: Three reference links pointed to `sdk/keyvault/test-resources.json` pinned at an old SHA — that file no longer exists (migrated to `.bicep`). Updated to point to `sdk/keyvault/test-resources.bicep` at `main`.
- **`docs.microsoft.com` → `learn.microsoft.com`**: Updated Azure CLI link at the bottom of the file.

### `doc/dev/mgmt/tests.md`
- **`docs.microsoft.com` → `learn.microsoft.com`**: Updated three Azure Active Directory tutorial links and one ARM REST API link. Microsoft migrated all docs from `docs.microsoft.com` to `learn.microsoft.com`.

### `doc/dev/mgmt/generation.md`
- **Deprecated build command**: Replaced `python setup.py bdist_wheel` with `python -m build --wheel` (the `setup.py` invocation is deprecated in modern Python tooling).

### `doc/dev/packaging.md`
- **RST file references in setup.py example**: The example read `README.rst` and `HISTORY.rst`. Current SDK packages use `README.md` and `CHANGELOG.md`. Updated the example to match current practice.
- **Python version classifiers**: The example only listed classifiers up to Python 3.12, but the support policy covers 3.10–3.13+. Added the 3.13 classifier.

### `doc/dev/docstring.md`
- **`docs.microsoft.com` → `learn.microsoft.com`**: Updated two Form Recognizer documentation links.

### `doc/request_builders.md` and `doc/send_request.md`
- **`docs.microsoft.com` → `learn.microsoft.com`**: Updated all reference links at the bottom of both files (azure-core, azure-identity, and authentication documentation URLs).

> Generated by [Documentation Consistency Check](https://github.com/Azure/azure-sdk-for-python/actions/runs/31357701936) · 146.6 AIC · ⌖ 14 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-documentation-inconsistencies-1bb2d58048901fb8`.
>
> **[Click here to create the pull request](https://github.com/Azure/azure-sdk-for-python/compare/main...doc/fix-documentation-inconsistencies-1bb2d58048901fb8?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 (238 of 238 lines)

```diff
From 6be649ca07e55f3eda21ef8ee3eabce9368e8f4e Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
Date: Mon, 10 Aug 2026 05:17:32 +0000
Subject: [PATCH] Fix documentation inconsistencies in doc/ folder

- dev_setup.md: Fix H1 title from 'Run SDK tests' to 'Developer Setup'
- tests.md: Update Python 3.10 Windows Store link to use apps.microsoft.com format
- tests.md: Replace internal review.learn.microsoft.com URL with public learn.microsoft.com
- tests.md: Update keyvault test-resources links from deleted .json (pinned SHA) to current .bicep file
- tests.md: Update docs.microsoft.com link to learn.microsoft.com
- mgmt/tests.md: Update docs.microsoft.com links to learn.microsoft.com
- mgmt/generation.md: Replace deprecated 'python setup.py bdist_wheel' with 'python -m build --wheel'
- packaging.md: Update setup.py example to use README.md/CHANGELOG.md instead of README.rst/HISTORY.rst
- packaging.md: Add Python 3.13 classifier to example (was only listing up to 3.12)
- docstring.md: Update docs.microsoft.com links to learn.microsoft.com
- request_builders.md: Update docs.microsoft.com links to learn.microsoft.com
- send_request.md: Update docs.microsoft.com links to learn.microsoft.com

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
doc/dev/dev_setup.md | 2 +-
doc/dev/docstring.md | 4 ++--
doc/dev/mgmt/generation.md | 2 +-
doc/dev/mgmt/tests.md | 6 +++---
doc/dev/packaging.md | 5 +++--
doc/dev/tests.md | 12 ++++++------
doc/request_builders.md | 18 +++++++++---------
doc/send_request.md | 18 +++++++++---------
8 files changed, 34 insertions(+), 33 deletions(-)

diff --git a/doc/dev/dev_setup.md b/doc/dev/dev_setup.md
index d126ede3..0a68c396 100644
--- a/doc/dev/dev_setup.md
+++ b/doc/dev/dev_setup.md
@@ -1,4 +1,4 @@
-# Run SDK tests
+# Developer Setup

This document describes how to create a dev environment in order to run SDK tests
o
... (truncated)
```

Contributor guide

Open the contributing guide

Research direction

Review the listed files under doc/, especially doc/dev/tests.md, doc/dev/packaging.md, and the management, docstring, request-builder, and send-request guides. Verify each referenced URL, filename, command, and Python classifier against the current repository and public documentation. Done means the documented names, links, and tooling examples match the current project state without stale or internal references.

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
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.