Azure / Azure/azure-sdk-for-python

[docs] Fix documentation inconsistencies in dev guides

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

This PR fixes several documentation inconsistencies found across `doc/dev/` by comparing the docs against current source code and repository conventions.

## Changes

### `doc/dev/tests.md`
- **Fixed numbered list (2 occurrences):** The list of supported auth tools (`AZURE_TEST_USE_*_AUTH`) skipped from item `2.` directly to `4.`, omitting `3.`. Changed `4. Azure Developer CLI` → `3. Azure Developer CLI` in both locations (lines ~178 and ~216).
- **Updated Python version example:** The virtual environment creation example referenced Python 3.14, which is an unreleased development version. Updated to Python 3.13 (the current stable release).

### `doc/dev/mgmt/generation.md`
- **Removed unnecessary `pip install setuptools` step:** The "Installing Necessary Dependencies" section instructed users to run `pip install setuptools` after `dev_setup.py`. This is not needed for modern packages using `pyproject.toml` and is not documented elsewhere as a requirement.
- **Replaced deprecated build command:** `python setup.py bdist_wheel` is deprecated (PEP 517). Updated to `python -m build`.

### `doc/dev/packaging.md`
- **Updated legacy `setup.py` example:** The example code read from `version.py` (without underscore) and `README.rst`. Current packages use `_version.py` (with leading underscore) and `README.md`. Updated the code snippet accordingly.
- **Marked Python 2 / `azure-nspkg` section as obsolete:** The "Note on Python 2" section stated that `extras_require` **MUST** include `azure-nspkg` for Python 2. Python 2 support was dropped on January 1st 2022; this requirement no longer applies. Reworded the section header and added an explicit obsolete notice.

### `doc/dev/static_type_checking.md`
- **Updated stale Python 2 type hint note:** The note said "some libraries use comment-style type hints due to legacy Python 2 code, but these will be updated." Since Python 2 support has been dropped, this "future work" framing is no longer accurate. Updated to simply state that annotation-style hints are required as Python 2 is no longer supported.

> Generated by [Documentation Consistency Check](https://github.com/Azure/azure-sdk-for-python/actions/runs/31996093993) · 174.8 AIC · ⌖ 12.8 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-5c0669ae2af3aeb2`.
>
> **[Click here to create the pull request](https://github.com/Azure/azure-sdk-for-python/compare/main...doc/fix-documentation-inconsistencies-5c0669ae2af3aeb2?expand=1&title=%5Bdocs%5D%20Fix%20documentation%20inconsistencies%20in%20dev%20guides)**

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 (133 of 133 lines)

```diff
From a48db3de1146963ef663f318c1d8a1c39553ad78 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
Date: Mon, 17 Aug 2026 05:02:13 +0000
Subject: [PATCH] doc: fix documentation inconsistencies in dev guides

- tests.md: fix numbered list skipping from 2 to 4 (two occurrences)
- tests.md: update Python 3.14 (unreleased) venv example to Python 3.13
- mgmt/generation.md: remove unnecessary 'pip install setuptools' step
- mgmt/generation.md: replace deprecated 'python setup.py bdist_wheel'
with 'python -m build'
- packaging.md: update version.py -> _version.py and README.rst -> README.md
in legacy setup.py example to match current package conventions
- packaging.md: mark 'Note on Python 2 / azure-nspkg' section as obsolete
since Python 2 support was dropped in 2022
- static_type_checking.md: update stale note about Python 2 comment-style
type hints to reflect that Python 2 is no longer supported

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
doc/dev/mgmt/generation.md | 3 +--
doc/dev/packaging.md | 10 ++++++----
doc/dev/static_type_checking.md | 2 +-
doc/dev/tests.md | 8 ++++----
4 files changed, 12 insertions(+), 11 deletions(-)

diff --git a/doc/dev/mgmt/generation.md b/doc/dev/mgmt/generation.md
index 73cb1553..6d3767d6 100644
--- a/doc/dev/mgmt/generation.md
+++ b/doc/dev/mgmt/generation.md
@@ -57,7 +57,6 @@ PS C:\dev\azure-sdk-for-python> .\.venv\Scripts\Activate.ps1 # Windows
3. Install Python dependencies:
```
(.venv) PS C:\dev\azure-sdk-for-python> python .\scripts\dev_setup.py -p azure-core
-(.venv) PS C:\dev\azure-sdk-for-python> pip install setuptools
```

### Generate the SDK
@@ -179,7 +178,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.

... (truncated)
```

Contributor guide

Open the contributing guide

Research direction

Review doc/dev/tests.md, doc/dev/mgmt/generation.md, doc/dev/packaging.md, and doc/dev/static_type_checking.md against the current source and repository conventions described in the issue. Verify the listed version, build, packaging, numbering, and Python 2 guidance changes, then confirm all four documents contain no remaining inconsistencies.

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
Active
Clarity
Clearly specified
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.