Skip to content

[docs] Fix documentation inconsistencies in doc/ folder#6

Draft
github-actions[bot] wants to merge 1 commit intomainfrom
docs/fix-documentation-inconsistencies-0b84e743a6bc8bba
Draft

[docs] Fix documentation inconsistencies in doc/ folder#6
github-actions[bot] wants to merge 1 commit intomainfrom
docs/fix-documentation-inconsistencies-0b84e743a6bc8bba

Conversation

@github-actions
Copy link
Copy Markdown

Summary

This PR fixes several inconsistencies found between the doc/ documentation and the actual source code/repository structure.


1. doc/dev/static_type_checking.md — Wrong pinned tool versions

Issue: The guide stated mypy was pinned to 1.9.0 and pyright to 1.1.287, but the actual source of truth (eng/tools/azure-sdk-tools/azpysdk/mypy.py and pyright.py) has MYPY_VERSION = "1.18.1" and PYRIGHT_VERSION = "1.1.405".

Fix: Updated all version references (linked text, pip install commands) to match the actual pinned versions in the tooling:

  • mypy: 1.9.01.18.1
  • pyright: 1.1.2871.1.405 (three occurrences: Run pyright section, Run verifytypes section)

2. doc/request_builders.md and doc/send_request.md — Broken async code examples

Issue 1 — NameError in exception handler: The sync and async example code used except HttpResponseError: (without as e) but then called print(str(e)). This would raise NameError: name 'e' is not defined at runtime.

Issue 2 — Deprecated internal API: The async examples called await response.load_body(). This method is marked as a backcompat-only internal alias in azure/core/rest/_aiohttp.py (backcompat_attrs = ["load_body"]). The correct public API is await response.read().

Fix:

  • except HttpResponseError:except HttpResponseError as e: (in both files)
  • await response.load_body()await response.read() (in both files)

3. doc/dev/packaging.md — Outdated setup.py example

Issue: The example setup.py had several divergences from actual current packages:

  • Read from 'version.py' but all actual packages (e.g., azure-storage-blob, azure-keyvault-secrets) use '_version.py'
  • Read from README.rst and HISTORY.rst (concatenated as long_description) — modern packages use README.md
  • Listed msrest, msrestazure, and azure-common as install_requires — these are deprecated dependencies no longer used in modern SDK packages
  • Used python_requires=">=3.8" and classifier Python :: 3.8 — the actual minimum enforced across core packages (azure-core, azure-storage-blob, etc.) and CI is 3.9

Fix: Updated the example setup.py to match current conventions:

  • 'version.py''_version.py'
  • README.rst/HISTORY.rstREADME.md with long_description_content_type='text/markdown'
  • Removed stale msrest/msrestazure/azure-common; replaced with azure-core>=1.30.0 as a representative modern dependency
  • Updated python_requires and classifiers from 3.8→3.9, added Python 3.13

4. doc/dev/tests.md and doc/dev/dev_setup.md — Stale Python 3.8 references

Issue: Both files referenced Python 3.8 as the minimum supported version, and tests.md included Windows Store links in the old (www.microsoft.com/redacted) format (not working for 3.8/3.9/3.10). The eng_sys_checks.mdand CI pipelines use Python 3.9 as the minimum, and core packages likeazure-coreandazure-storage-blobdeclarepython_requires=">=3.9"`.

Fix:

  • Updated "Python 3.8 and up" → "Python 3.9 and up" in both files
  • Removed Python 3.8 Windows Store link entry; updated 3.9 and 3.10 links to the current apps.microsoft.com/detail/... format (matching the 3.11/3.12 links already present)
  • Updated py -3.8 comment in dev_setup.mdpy -3.9

Generated by Documentation Consistency Check ·

Warning

⚠️ Firewall blocked 2 domains

The following domains were blocked by the firewall during workflow execution:

  • docs.microsoft.com
  • releaseassets.githubusercontent.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "docs.microsoft.com"
    - "releaseassets.githubusercontent.com"

See Network Configuration for more information.

- static_type_checking.md: Update pinned mypy version from 1.9.0 to 1.18.1
  and pyright version from 1.1.287 to 1.1.405 to match azpysdk/mypy.py and
  azpysdk/pyright.py source of truth.

- request_builders.md / send_request.md: Fix two bugs in async code examples:
  1. 'except HttpResponseError:' was missing 'as e', causing NameError when
     the handler calls print(str(e)).
  2. 'await response.load_body()' is a backcompat-only internal method; replace
     with the public API 'await response.read()'.

- packaging.md: Update the setup.py example to reflect current conventions:
  - Read from '_version.py' (not 'version.py') — matches actual packages.
  - Use README.md with text/markdown content type instead of README.rst/HISTORY.rst.
  - Remove deprecated msrest, msrestazure, azure-common install_requires.
  - Update minimum Python version from 3.8 to 3.9 throughout; add Python 3.13
    classifier.

- tests.md / dev_setup.md: Update minimum Python version references from 3.8
  to 3.9 (matching azure-core, azure-storage-blob, and CI configuration); fix
  old Microsoft Store URL format for Python 3.9/3.10 to apps.microsoft.com
  format; remove Python 3.8 entry since it is no longer supported.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@github-actions github-actions bot added automated documentation Improvements or additions to documentation labels Mar 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

automated documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

0 participants