Azure / Azure/azure-sdk-for-python

[docs] Fix documentation inconsistencies in doc/ folder

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.