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 two documentation inconsistencies found during a review of all markdown files under `doc/`.
### Changes
#### `doc/dev/mgmt/generation.md`
**Issue**: The "Using Raw Autorest" section instructed users to run `python setup.py bdist_wheel` to build a wheel from the generated code. This is the legacy, deprecated build interface removed from modern Python packaging. PEP 517 (adopted in pip 19+) replaced it with `python -m build`.
**Fix**: Updated the command to `python -m build` (with a note to `pip install build` first).
Before:
```
call `python setup.py bdist_wheel`
```
After:
```
call `python -m build` (requires `pip install build`)
```
---
#### `doc/dev/static_type_checking.md`
**Issue**: The note "Note that the key should be the namespace of where the `py.typed` file is found." appeared directly after the `pyproject.toml` example which uses `pytyped = ["py.typed"]` as the key. This is misleading: the key in `pyproject.toml` is the literal string `pytyped` (consistent with every package in the repo), not the package namespace. The note actually describes the `setup.py` `package_data` dict, where the key IS the namespace (e.g. `"azure.core"`).
**Fix**: Clarified that the note applies to the `setup.py` case only, to avoid confusing readers of the `pyproject.toml` instructions.
Before:
```
Note that the key should be the namespace of where the `py.typed` file is found.
```
After:
```
Note that in the `setup.py` case, the key should be the namespace of where the `py.typed` file is found (e.g. `"azure.core"`).
```
---
### Verification
- Both changes are consistent with actual package conventions in the repository (e.g. `sdk/template/azure-template/pyproject.toml`, `sdk/core/azure-core/pyproject.toml`).
- No functional code was changed.
> Generated by [Documentation Consistency Check](https://github.com/Azure/azure-sdk-for-python/actions/runs/29227290602) · 93.8 AIC · ⌖ 12 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-0ff573227631f67a`.
>
> **[Click here to create the pull request](https://github.com/Azure/azure-sdk-for-python/compare/main...doc/fix-inconsistencies-2026-07-0ff573227631f67a?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 (46 of 46 lines)
```diff
From e7050876751695947e0a897ab763ed0310755dc3 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
Date: Mon, 13 Jul 2026 05:55:09 +0000
Subject: [PATCH] doc: fix documentation inconsistencies
- doc/dev/mgmt/generation.md: Replace deprecated 'python setup.py bdist_wheel'
with 'python -m build' (PEP 517 standard build command)
- doc/dev/static_type_checking.md: Clarify that the 'key should be the namespace'
note applies to the setup.py case, not pyproject.toml (where the key is 'pytyped')
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
doc/dev/mgmt/generation.md | 2 +-
doc/dev/static_type_checking.md | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/doc/dev/mgmt/generation.md b/doc/dev/mgmt/generation.md
index 73cb1553..13964f7d 100644
--- a/doc/dev/mgmt/generation.md
+++ b/doc/dev/mgmt/generation.md
@@ -179,7 +179,7 @@ If you're doing basic testing and want to minimal set of parameters:
And that's it! You should now have Python code ready to test. Note that this generation is for testing only and should not be sent to a customer or published to PyPI.
-This command generate code only. If you want to generate a [wheel](https://pythonwheels.com/) file to share this code, add the `--basic-setup-py` option to generate a basic `setup.py` file and call `python setup.py bdist_wheel`.
+This command generate code only. If you want to generate a [wheel](https://pythonwheels.com/) file to share this code, add the `--basic-setup-py` option to generate a basic `setup.py` file and call `python -m build` (requires `pip install build`).
#### Examples
diff --git a/doc/dev/static_type_checking.md b/doc/dev/static_type_checking.md
index fcd0d34e..579f1510 100644
--- a/doc/dev/static_type_checking.md
+++ b/doc/dev/static_type_checking.md
@@ -120,7 +120,7 @@ given the expressiveness of Python as a language. So, in practice, what should y
pytyped = ["py.typed"]
... (truncated)
```
Contributor guide
Research direction
Read doc/dev/mgmt/generation.md and doc/dev/static_type_checking.md at the sections described in the issue, then compare them with the repository's package conventions in sdk/template/azure-template/pyproject.toml and sdk/core/azure-core/pyproject.toml. Done means the wheel-building instruction uses the modern command and the py.typed note clearly applies only to the setup.py case; no functional code should change.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 35/100