Azure / Azure/azure-sdk-for-python

[docs] Fix documentation inconsistencies in developer guides

Aperta
#48,147 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
agentic-workflows automated documentation
Lingua principale
Python
Stelle
5.6k
Fork
3.4k
Merge medio
2g 2h
PR unite (30g)
202

Descrizione

## Summary

This PR fixes three inconsistencies found in the developer documentation under `doc/`:

### 1. Broken `conftest.py` link in `doc/dev/mgmt/tests.md`

The link pointed to `sdk/advisor/azure-mgmt-advisor/tests/conftest.py`, which does not exist in the repository. The `azure-mgmt-advisor` package uses auto-generated tests, and the conftest lives at `sdk/advisor/azure-mgmt-advisor/generated_tests/conftest.py`.

**Fix:** Updated the URL to point to the correct `generated_tests/conftest.py` path.

### 2. Stale line-number anchors in `doc/dev/pylint_checking.md`

The guide linked to specific line numbers in `eng/tools/azure-sdk-tools/azpysdk/pylint.py` to show where the pinned pylint version and the `azure-pylint-guidelines-checker` version are defined. Both anchors were off:

- `#L17` → `#L16` (`PYLINT_VERSION = "4.0.4"`)
- `#L61` → `#L70` (`azure-pylint-guidelines-checker==0.5.7`)

**Fix:** Updated the anchors to match the current line numbers.

### 3. Outdated Python 2 reference in `doc/dev/static_type_checking.md`

A note said type comments are used in "legacy code supporting Python 2". Python 2 support was dropped years ago and no active library in this repo uses comment-style type hints for Python 2 compatibility.

**Fix:** Simplified the note to just say "Use inline annotation style instead."

> Generated by [Documentation Consistency Check](https://github.com/Azure/azure-sdk-for-python/actions/runs/29720083162) · 119.7 AIC · ⌖ 12.4 AIC · ⊞ 5.9K · [◷](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-092e77602d1e7e2b`.
>
> **[Click here to create the pull request](https://github.com/Azure/azure-sdk-for-python/compare/main...doc/fix-inconsistencies-2026-092e77602d1e7e2b?expand=1&title=%5Bdocs%5D%20Fix%20documentation%20inconsistencies%20in%20developer%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 (65 of 65 lines)

```diff
From a4108fe3f6e7e1fca1575d0c3a3dad3dbae9da64 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
Date: Mon, 20 Jul 2026 05:56:10 +0000
Subject: [PATCH] doc: fix inconsistencies in developer documentation

- Fix broken link in doc/dev/mgmt/tests.md: conftest.py example
pointed to sdk/advisor/azure-mgmt-advisor/tests/conftest.py which
does not exist; corrected to generated_tests/conftest.py
- Fix stale line-number anchors in doc/dev/pylint_checking.md:
pylint.py#L17 -> #L16 (PYLINT_VERSION) and #L61 -> #L70
(azure-pylint-guidelines-checker install line)
- Remove outdated Python 2 reference in doc/dev/static_type_checking.md:
the note about type comments being used for Python 2 legacy code is
no longer relevant since Python 2 support was dropped

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

diff --git a/doc/dev/mgmt/tests.md b/doc/dev/mgmt/tests.md
index 7f7bfdd4..7328a29b 100644
--- a/doc/dev/mgmt/tests.md
+++ b/doc/dev/mgmt/tests.md
@@ -153,7 +153,7 @@ Management plane SDKs are those that are formatted `azure-mgmt-xxxx`, otherwise

### Tips:
After the migration of the test proxy, `conftests.py` needs to be configured under the tests folder.

-* For a sample about `conftest.py`, see [conftest.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/advisor/azure-mgmt-advisor/tests/conftest.py).

+* For a sample about `conftest.py`, see [conftest.py](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/advisor/azure-mgmt-advisor/generated_tests/conftest.py).

* For more information about test proxy, see [TestProxy][testproxy].

### Example 1: Basic Azure service interaction and recording
diff --git a/doc/dev/pylint_checking.md b/doc/dev/pylint_checking.md
index 7bee34e3..190eedf2
... (truncated)
```

Guida per i contributori

Apri la guida per i contributori

Direzione di ricerca

Esamina doc/dev/mgmt/tests.md, doc/dev/pylint_checking.md e doc/dev/static_type_checking.md insieme ai percorsi e agli anchor del repository a cui si fa riferimento. Verifica che il link a conftest.py sia risolto, che i link di pylint puntino alle definizioni indicate e che la nota sul controllo dei tipi non faccia più riferimento a Python 2; i controlli della documentazione dovrebbero passare con solo questi tre aggiornamenti.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
python
Ambito
documentation
Tipo di issue
Documentazione
Difficoltà
2/5
Tempo stimato
1-3 ore
Stato di attività
Tranquilla
Chiarezza
Specificata chiaramente
Idoneità per principianti
35/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.