[Docs] Misc updates

doc/README.md

@@ -13,6 +13,7 @@ This folder contains documentation for the Azure SDK for Python repository.
 - [Send Request](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/send_request.md) - Send request pattern documentation
 - [Analyze Check Versions](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/analyze_check_versions.md) - Check version analysis
 - [Tool Usage Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/tool_usage_guide.md) - How to use the `azpysdk` CLI tool
+- [SDK and AI](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/sdk_and_ai.md) - AI-assisted SDK development guidance
 
 ## Developer Documentation
 
@@ -47,7 +48,6 @@ See the [dev](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/)
 - [Customize Long Running Operations](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/customize_long_running_operation.md) - LRO customization
 - [CredScan Process](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/credscan_process.md) - Credential scanning
 - [Recording Migration Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/recording_migration_guide.md) - Migrating test recordings
-- [Engineering Assumptions](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/engineering_assumptions.md) - SDK engineering assumptions
 - [Conda Builds](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/conda-builds.md) / [Release](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/conda-release.md) / [Dev Release](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/conda-release-dev.md) - Conda packaging
 
 ## Sphinx Reference Documentation

doc/dev/README.md

@@ -2,27 +2,55 @@
 
 This folder contains documentation for developers of SDKs: internal teams at Microsoft, or advanced contributors.
 
-Overview of the documents:
-- [Developer Set-Up](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/dev_setup.md) : How to create a development environment for this repo
-- [Release](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/release.md) : How to release a package when ready
-- [Packaging](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/packaging.md) : How to organize packaging information for packages under `azure`
-- [Changelog](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/changelog_updates.md) : How to document package changes using Chronus (for packages with `pyproject.toml`)
-- [Testing](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/tests.md): How to write unit and functional tests for a library
-- [Docstrings](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/docstring.md): How to document an SDK (API View) and our documentation at [MS Docs][ms_docs] and the [azure.github.io][azure_github_io] site.
-- [Type Hints and Type Checking](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/static_type_checking.md) / [Cheatsheet](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/static_type_checking_cheat_sheet.md): How to add type hints to your library code and run type checking.
+## Getting Started
 
-The [mgmt](https://github.com/Azure/azure-sdk-for-python/tree/main/doc/dev/mgmt) folder contains information specific to management packages (i.e. packages prefixed by `azure-mgmt`)
+- [Developer Set-Up](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/dev_setup.md) - How to create a development environment for this repo
+- [Release](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/release.md) - How to release a package when ready
+- [Packaging](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/packaging.md) - How to organize packaging information for packages under `azure`
+- [Changelog](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/changelog_updates.md) - How to document package changes using Chronus (for packages with `pyproject.toml`)
+- [Package Versioning](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/package_version/package_version_rule.md) - Version numbering rules
 
-### Troubleshooting
+## Testing
+
+- [Testing](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/tests.md) - How to write unit and functional tests for a library
+- [Advanced Testing](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/tests-advanced.md) - Advanced testing topics
+- [Performance Testing](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/perfstress_tests.md) - How to write and run perf tests
+- [Recording Migration Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/recording_migration_guide.md) - Migrating test recordings
+- [CredScan Process](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/credscan_process.md) - Credential scanning
+
+## Code Quality & Documentation
+
+- [Docstrings](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/docstring.md) - How to document an SDK (API View) and our documentation at [MS Learn][ms_learn] and the [azure.github.io][azure_github_io] site
+- [Type Hints and Type Checking](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/static_type_checking.md) / [Cheatsheet](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/static_type_checking_cheat_sheet.md) - How to add type hints and run type checking
+- [Pylint](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/pylint_checking.md) - Pylint checking guidance
+- [Sample Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/sample_guide.md) - How to write SDK samples
+- [Code Snippets](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/code_snippets.md) - How to include code snippets in docs
+
+## Troubleshooting
 
 - [Common Issues and FAQ](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/common_issues.md) - Common SDK issues and how to resolve them
+- [Test Proxy Troubleshooting](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/test_proxy_troubleshooting.md) - Test proxy issues
+- [Debug Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/debug_guide.md) - Debugging tips
+- [Resolve Issues Effectively](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/issues/resolve_issues_effectively.md) - How to triage and resolve customer issues
+- [Find SDK in CLI Command](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/find_sdk/find_sdk_in_cli_command.md) - Mapping CLI commands to SDK packages
 
-### Code Generation
+## Code Generation
 
 - [Dataplane SDK Generation](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/dataplane_generation.md) - Generate a dataplane SDK from a TypeSpec definition
+- [Management Plane](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/mgmt/) - Management plane SDK documentation
+- [Customize Long Running Operations](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/customize_long_running_operation.md) - LRO customization
+
+## AI-Assisted Development
+
+- [AI Prompt Workflow](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/ai/ai_prompt_workflow.md) - Using AI agents for SDK development
+- [TypeSpec Generation with AI](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/ai/typespec_generation.md) - AI-assisted TypeSpec generation
+
+## Conda
 
-### Additional Topics
+- [Conda Builds](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/conda-builds.md) - Conda packaging
+- [Conda Release](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/conda-release.md) - Conda release process
+- [Conda Dev Release](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/conda-release-dev.md) - Conda dev release process
 
 <!-- links -->
-[ms_docs]: https://docs.microsoft.com/python/api/overview/azure/appconfiguration-readme?view=azure-python
+[ms_learn]: https://learn.microsoft.com/python/api/overview/azure/appconfiguration-readme?view=azure-python
 [azure_github_io]: https://azure.github.io/azure-sdk-for-python/

doc/dev/code_snippets.md

@@ -29,7 +29,7 @@ https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/samp
 
 Instead of copying the code snippet into README which is hard to maintain and validate, we add reference to the sample snippet in README. We use the annotation `\<!-- SNIPPET:file_name.snippet_name-->` to refer the code snippet in README file.
 
-If you have a file in `samples\text_example_async.py` with a snippet named `asyncio`, you can reference it in your README like:
+If you have a file in `samples/test_example_async.py` with a snippet named `asyncio`, you can reference it in your README like:
 
 ````markdown
 <!-- SNIPPET:test_example_async.asyncio -->
@@ -40,7 +40,7 @@ If you have a file in `samples\text_example_async.py` with a snippet named `asyn
 
 > Make sure you include a Python code fence within the snippet reference!
 
-## Run update_snippet tool 
+## Run update_snippet tool
 
 The update_snippet tool is included in the [azpysdk CLI](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/tool_usage_guide.md), which is installed with `azure-sdk-tools`.
 

doc/dev/dev_setup.md

@@ -25,10 +25,19 @@ or execute the various commands available in the toolbox.
     You can initialize a virtual environment this way:
 
     ```
-    python -m venv env # Might be "python3" or "py -3.8" depending on your Python installation
-    source env/bin/activate      # Linux shell (Bash, ZSH, etc.) only
-    ./env/scripts/activate       # PowerShell only
-    ./env/scripts/activate.bat   # Windows CMD only
+    python -m venv env # Might be "python3" or "py" depending on your Python installation
+    source env/bin/activate        # Linux shell (Bash, ZSH, etc.)
+    .\env\Scripts\Activate.ps1     # PowerShell
+    .\env\Scripts\activate.bat     # Windows CMD
+    ```
+
+    Alternatively, you can use [uv][uv] which is faster and handles Python version management automatically:
+
+    ```
+    uv venv
+    source .venv/bin/activate    # Linux shell (Bash, ZSH, etc.)
+    .\.venv\Scripts\Activate.ps1 # PowerShell
+    .\.venv\Scripts\activate.bat # Windows CMD
     ```
 
 4. Setup your development environment
@@ -40,9 +49,15 @@ or execute the various commands available in the toolbox.
     azure-sdk-for-python/sdk/formrecognizer/azure-ai-formrecognizer> pip install -e .
     ```
 
+    Or with uv:
+    ```
+    azure-sdk-for-python/sdk/formrecognizer/azure-ai-formrecognizer> uv pip install -r dev_requirements.txt
+    azure-sdk-for-python/sdk/formrecognizer/azure-ai-formrecognizer> uv pip install -e .
+    ```
+
 5.  Create a .env file to store your secrets.
 
-    The recommended place to store your .env file in the root of the SDK repository, as it will be gitignored.
+    Create a `.env` file to store secrets needed for live tests (e.g. connection strings, resource endpoints). Place it in the root of the SDK repository where it is gitignored. See [tests.md][tests] for details on which environment variables are needed for each package.
 
 ## Follow test-running guidance
 
@@ -54,3 +69,4 @@ After following the steps above, you'll be able to run recorded SDK tests with `
 [python_312]: https://apps.microsoft.com/detail/9ncvdn91xzqp
 [tests]: https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/tests.md
 [virtual_environment]: https://docs.python.org/3/tutorial/venv.html
+[uv]: https://docs.astral.sh/uv/

doc/dev/find_sdk/find_sdk_in_cli_command.md

@@ -1,4 +1,4 @@
-How to Find the SDK in CLI 
+How to Find the SDK in CLI
 ======
 
 This article aims to provide a guide for customer to find the sdk in Azure CLI.
@@ -91,6 +91,6 @@ In this file, you could search the function name to find the function definition
 Above the `begin_delete` function, you could find it from [here](https://github.com/Azure/azure-sdk-for-python/blob/9d3f4aaf3125cc6ae63c8425d0d15d20d488d61e/sdk/resources/azure-mgmt-resource/azure/mgmt/resource/resources/operations/_operations.py#L4188).
 The same, the `create_or_update` function is [here](https://github.com/Azure/azure-sdk-for-python/blob/9d3f4aaf3125cc6ae63c8425d0d15d20d488d61e/sdk/resources/azure-mgmt-resource/azure/mgmt/resource/resources/operations/_operations.py#L4019).
 
-Finally, you also could find the usage of function by [Azure doc](https://docs.microsoft.com/azure/developer/python/sdk/examples/azure-sdk-example-resource-group#3-write-code-to-provision-a-resource-group) or [Azure samples](https://github.com/Azure-Samples/azure-samples-python-management).
+Finally, you also could find the usage of function by [Azure doc](https://learn.microsoft.com/azure/developer/python/sdk/examples/azure-sdk-example-resource-group#3-write-code-to-provision-a-resource-group) or [Azure samples](https://github.com/Azure-Samples/azure-samples-python-management).
 
 Feel free to contact Azure SDK team at any time through any channels. We are passionate to build the world-class cloud product.

doc/dev/issues/resolve_issues_effectively.md

@@ -29,7 +29,7 @@ If you can provide detailed reproduction steps, it will help us locate and solve
 If the code you use needs to set wait() function for the Long Running Operation to wait for the result, it should be the SDK of Track1. We have stopped maintenance at present.
 
 We strongly recommend that you update the SDK version. Then you will find that in the SDK of Track2, we all use the function name prefixed with `begin_` for LRO operations, and the result() method can be used to get the returned result.
-(More Details: [guidance][guidance]) 
+(More Details: [guidance][guidance])
 
 ### Possible Error from Service
 Since the python SDK is generated based on the [rest API][rest API], it will not deliberately change the returned results. So if you think the returned result is not as expected, please open the issue under the [rest issue][rest issue].
@@ -56,7 +56,6 @@ Fault localization is critical to bug fix. Some tips:
 
 2. Step-by-step debugging. Most modern IDEs provide integrated debugging experience.
 
-
 ### Fix the bug
 
 Once you have confirmed the bug and found the fault location, it should be easy to fix the bug. Add a sample if it is missing. Remember to tell users when the fix will released.
@@ -66,9 +65,6 @@ Once you have confirmed the bug and found the fault location, it should be easy
 
 If the issue is not from the SDK but from the [rest API][rest API], you can reply to the user and reopen the issue in the appropriate place.
 
-### Error like (AttributeError: 'PipelineResponse' object has no attribute 'get')
-When this error occurs, you can check the version of `msrest` and upgrade it to latest version then try again.
-
 
 [sample repo]: https://github.com/Azure-Samples/azure-samples-python-management
 [rest API]: https://github.com/Azure/azure-rest-api-specs