From 983981ca03624c4101f090c975a91c90e9344436 Mon Sep 17 00:00:00 2001 From: Hashim Khan <64767361+Hashim1999164@users.noreply.github.com> Date: Thu, 13 Aug 2026 04:37:38 +0500 Subject: [PATCH] Fix documentation inconsistencies in the doc folder Correct outdated titles, migrated learn.microsoft.com links, keyvault test-resources references, packaging examples, and deprecated wheel build guidance so contributor docs match the current repo. Fixes #48507. --- doc/dev/dev_setup.md | 2 +- doc/dev/docstring.md | 4 ++-- doc/dev/mgmt/generation.md | 2 +- doc/dev/mgmt/tests.md | 6 +++--- doc/dev/packaging.md | 5 +++-- doc/dev/tests.md | 12 ++++++------ doc/request_builders.md | 18 +++++++++--------- doc/send_request.md | 18 +++++++++--------- 8 files changed, 34 insertions(+), 33 deletions(-) diff --git a/doc/dev/dev_setup.md b/doc/dev/dev_setup.md index d126ede3d418..0a68c396cb87 100644 --- a/doc/dev/dev_setup.md +++ b/doc/dev/dev_setup.md @@ -1,4 +1,4 @@ -# Run SDK tests +# Developer Setup This document describes how to create a dev environment in order to run SDK tests or execute the various commands available in the toolbox. diff --git a/doc/dev/docstring.md b/doc/dev/docstring.md index 876c67c7e736..ab9036ba5ad2 100644 --- a/doc/dev/docstring.md +++ b/doc/dev/docstring.md @@ -24,14 +24,14 @@ A method docstring is annotated by the Python long-string `""""""` ri externally accessible Azure storage blob container URI (preferably a Shared Access Signature URI). Note that a container URI (without SAS) is accepted only when the container is public. See `SAS container details - `__ + `__ for more details. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg', 'image/png', 'image/tiff', or 'image/bmp'. Other types of content in the container is ignored. :param str training_files_url: An Azure Storage blob container's SAS URI. A container URI (without SAS) can be used if the container is public. For more information on setting up a training data set, see: - https://docs.microsoft.com/azure/cognitive-services/form-recognizer/build-training-data-set + https://learn.microsoft.com/azure/cognitive-services/form-recognizer/build-training-data-set :param bool use_training_labels: Whether to train with labels or not. Corresponding labeled files must exist in the blob container if set to `True`. :keyword str prefix: A case-sensitive prefix string to filter documents in the source path for diff --git a/doc/dev/mgmt/generation.md b/doc/dev/mgmt/generation.md index 73cb155305c2..f0797e0b6681 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 --wheel`. #### Examples diff --git a/doc/dev/mgmt/tests.md b/doc/dev/mgmt/tests.md index 7f7bfdd4ff87..a1543493e5e4 100644 --- a/doc/dev/mgmt/tests.md +++ b/doc/dev/mgmt/tests.md @@ -52,14 +52,14 @@ There are several ways to authenticate to Azure, but to be able to record test H ### Get a token with Active Directory application and service principal Follow this detailed tutorial to set up an Active Directory application and service principal: -https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal +https://learn.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal To use the credentials from Python, you need: * Application ID (a.k.a. client ID) * Authentication key (a.k.a. client secret) * Tenant ID * Subscription ID from the Azure portal -[This section of the above tutorial](https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal#get-tenant-and-app-id-values-for-signing-in) describes where to find them (besides the subscription ID, which is in the "Overview" section of the "Subscriptions" blade.) +[This section of the above tutorial](https://learn.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal#get-tenant-and-app-id-values-for-signing-in) describes where to find them (besides the subscription ID, which is in the "Overview" section of the "Subscriptions" blade.) The recommended practice is to store these three values in environment variables called `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, and `AZURE_CLIENT_SECRET`. To set an environment variable use the following commands: ```Shell @@ -343,7 +343,7 @@ class TestMgmtSearch(AzureMgmtRecordedTestCase): ``` -[arm_apis]: https://docs.microsoft.com/rest/api/resources/ +[arm_apis]: https://learn.microsoft.com/rest/api/resources/ [azure_sdk_tools]: https://github.com/Azure/azure-sdk-for-python/tree/main/eng/tools/azure-sdk-tools [azure_portal]: https://portal.azure.com/ [decorators]: https://www.python.org/dev/peps/pep-0318/ diff --git a/doc/dev/packaging.md b/doc/dev/packaging.md index 3e6a8ee8031d..96707bb7acbd 100644 --- a/doc/dev/packaging.md +++ b/doc/dev/packaging.md @@ -96,9 +96,9 @@ with open(os.path.join(package_folder_path, 'version.py'), 'r') as fd: if not version: raise RuntimeError('Cannot find version information') -with open('README.rst', encoding='utf-8') as f: +with open('README.md', encoding='utf-8') as f: readme = f.read() -with open('HISTORY.rst', encoding='utf-8') as f: +with open('CHANGELOG.md', encoding='utf-8') as f: history = f.read() setup( @@ -118,6 +118,7 @@ setup( 'Programming Language :: Python :: 3.10', 'Programming Language :: Python :: 3.11', 'Programming Language :: Python :: 3.12', + 'Programming Language :: Python :: 3.13', 'License :: OSI Approved :: MIT License', ], python_requires=">=3.10", diff --git a/doc/dev/tests.md b/doc/dev/tests.md index 86b8a00a4b04..22aad1d5e79a 100644 --- a/doc/dev/tests.md +++ b/doc/dev/tests.md @@ -34,7 +34,7 @@ The Azure SDK Python team creates libraries that are compatible with Python 3.10 Python virtual environment for Python 3.10, but having a virtual environment for each minor version can make it easier to debug PRs locally. -- Python 3.10+: Use the [python website](https://www.python.org/downloads/) or the one-click experience from the Windows store ([3.10](https://www.microsoft.com/p/python-310/9pjpw5ldxlz5), [3.11](https://apps.microsoft.com/detail/9nrwmjp3717k?hl=en-us&gl=US), [3.12](https://apps.microsoft.com/detail/9ncvdn91xzqp?hl=en-us&gl=US)) (Windows only). +- Python 3.10+: Use the [python website](https://www.python.org/downloads/) or the one-click experience from the Windows store ([3.10](https://apps.microsoft.com/detail/9pjpw5ldxlz5?hl=en-us&gl=US), [3.11](https://apps.microsoft.com/detail/9nrwmjp3717k?hl=en-us&gl=US), [3.12](https://apps.microsoft.com/detail/9ncvdn91xzqp?hl=en-us&gl=US)) (Windows only). ```cmd @@ -55,7 +55,7 @@ C:\Users> -m venv py314_venv In the root directory of our SDK, a number of mandatory files have been added. When creating your own SDK, these files can be copied from the [`sdk/template`](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/template) project, and modified to your needs. -- README.md. This is the description and guidance for customers or your SDK. Please see the guide on writing a README to make sure you have the complete [content requirements and formatting](https://review.learn.microsoft.com/help/platform/reference-document-sdk-client-libraries#readme). +- README.md. This is the description and guidance for customers or your SDK. Please see the guide on writing a README to make sure you have the complete [content requirements and formatting](https://learn.microsoft.com/help/platform/reference-document-sdk-client-libraries#readme). - CHANGELOG.md. This is where you will add the summary of changes for each new release. Please see [the guidance](https://azure.github.io/azure-sdk/policies_releases.html#changelog-guidance) for correct formatting. - pyproject.toml. This is the package configuration file for your Python SDK. Please see [the guide on Python packaging][packaging] for details on customizing this for a specific package. - setup.py / setup.cfg. **Legacy:** older packages use these instead of `pyproject.toml` to build the Python package. New packages should use `pyproject.toml`. Please see [the guide on Python packaging][packaging] for details. @@ -576,7 +576,7 @@ For information about more advanced testing scenarios, refer to the [advanced te [advanced_tests_notes]: https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/tests-advanced.md -[azure_cli_service_principal]: https://docs.microsoft.com/cli/azure/ad/sp?view=azure-cli-latest#az-ad-sp-create-for-rbac +[azure_cli_service_principal]: https://learn.microsoft.com/cli/azure/ad/sp?view=azure-cli-latest#az-ad-sp-create-for-rbac [azure_portal]: https://portal.azure.com/ [azure_recorded_test_case]: https://github.com/Azure/azure-sdk-for-python/blob/main/eng/tools/azure-sdk-tools/devtools_testutils/azure_recorded_testcase.py [central_conftest]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/conftest.py @@ -585,9 +585,9 @@ For information about more advanced testing scenarios, refer to the [advanced te [env_var_options]: https://github.com/Azure/azure-sdk-for-python/tree/main/eng/tools/azure-sdk-tools/devtools_testutils#hide-secret-environment-variables-in-test-logs [get_credential]: https://github.com/Azure/azure-sdk-for-python/blob/4df650d2ce4c292942009ed648cae21eb9c2121d/eng/tools/azure-sdk-tools/devtools_testutils/azure_recorded_testcase.py#L78 [git_setup]: https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup -[kv_test_resources]: https://github.com/Azure/azure-sdk-for-python/blob/fbdb860630bcc13c1e355828231161849a9bd5a4/sdk/keyvault/test-resources.json -[kv_test_resources_outputs]: https://github.com/Azure/azure-sdk-for-python/blob/fbdb860630bcc13c1e355828231161849a9bd5a4/sdk/keyvault/test-resources.json#L255 -[kv_test_resources_resources]: https://github.com/Azure/azure-sdk-for-python/blob/fbdb860630bcc13c1e355828231161849a9bd5a4/sdk/keyvault/test-resources.json#L116 +[kv_test_resources]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/keyvault/test-resources.bicep +[kv_test_resources_outputs]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/keyvault/test-resources.bicep +[kv_test_resources_resources]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/keyvault/test-resources.bicep [manage_recordings]: https://github.com/Azure/azure-sdk-for-python/blob/main/scripts/manage_recordings.py [packaging]: https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/packaging.md [proxy_general_docs]: https://github.com/Azure/azure-sdk-tools/blob/main/tools/test-proxy/Azure.Sdk.Tools.TestProxy/README.md diff --git a/doc/request_builders.md b/doc/request_builders.md index 57678dd83f93..373e0fc6808d 100644 --- a/doc/request_builders.md +++ b/doc/request_builders.md @@ -281,17 +281,17 @@ You can file issues [here][issues] in our repo. -[azure_core_docs]: https://docs.microsoft.com/python/api/overview/azure/core-readme?view=azure-python -[azure_identity_docs]: https://docs.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python -[http_response]: https://docs.microsoft.com/python/api/azure-core/azure.core.pipeline.transport.httpresponse?view=azure-python +[azure_core_docs]: https://learn.microsoft.com/python/api/overview/azure/core-readme?view=azure-python +[azure_identity_docs]: https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python +[http_response]: https://learn.microsoft.com/python/api/azure-core/azure.core.pipeline.transport.httpresponse?view=azure-python [azure_identity_pip]: https://pypi.org/project/azure-identity/ -[aad_authentication]: https://docs.microsoft.com/azure/cognitive-services/authentication?tabs=powershell#authenticate-with-an-authentication-token +[aad_authentication]: https://learn.microsoft.com/azure/cognitive-services/authentication?tabs=powershell#authenticate-with-an-authentication-token [identity_credentials]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity#credentials -[default_azure_credential]: https://docs.microsoft.com/python/api/azure-identity/azure.identity.defaultazurecredential?view=azure-python -[azure_key_credential]: https://docs.microsoft.com/python/api/azure-core/azure.core.credentials.azurekeycredential?view=azure-python -[bearer_token_credential_policy]: https://docs.microsoft.com/python/api/azure-core/azure.core.pipeline.policies.bearertokencredentialpolicy?view=azure-python -[azure_key_credential_policy]: https://docs.microsoft.com/python/api/azure-core/azure.core.pipeline.policies.azurekeycredentialpolicy?view=azure-python -[azure_core_exceptions]: https://docs.microsoft.com/python/api/azure-core/azure.core.exceptions?view=azure-python +[default_azure_credential]: https://learn.microsoft.com/python/api/azure-identity/azure.identity.defaultazurecredential?view=azure-python +[azure_key_credential]: https://learn.microsoft.com/python/api/azure-core/azure.core.credentials.azurekeycredential?view=azure-python +[bearer_token_credential_policy]: https://learn.microsoft.com/python/api/azure-core/azure.core.pipeline.policies.bearertokencredentialpolicy?view=azure-python +[azure_key_credential_policy]: https://learn.microsoft.com/python/api/azure-core/azure.core.pipeline.policies.azurekeycredentialpolicy?view=azure-python +[azure_core_exceptions]: https://learn.microsoft.com/python/api/azure-core/azure.core.exceptions?view=azure-python [azure_core_http_request]: https://azuresdkdocs.z19.web.core.windows.net/python/azure-core/latest/azure.core.html#azure.core.rest.HttpRequest [azure_core_http_response]: https://azuresdkdocs.z19.web.core.windows.net/python/azure-core/latest/azure.core.html#azure.core.rest.HttpResponse [azure_core_async_http_response]: https://azuresdkdocs.z19.web.core.windows.net/python/azure-core/latest/azure.core.html#azure.core.rest.AsyncHttpResponse diff --git a/doc/send_request.md b/doc/send_request.md index 4f6b8df3bfa2..0399a3ec5457 100644 --- a/doc/send_request.md +++ b/doc/send_request.md @@ -195,17 +195,17 @@ You can file issues [here][issues] in our repo. -[azure_core_docs]: https://docs.microsoft.com/python/api/overview/azure/core-readme?view=azure-python -[azure_identity_docs]: https://docs.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python -[http_response]: https://docs.microsoft.com/python/api/azure-core/azure.core.pipeline.transport.httpresponse?view=azure-python +[azure_core_docs]: https://learn.microsoft.com/python/api/overview/azure/core-readme?view=azure-python +[azure_identity_docs]: https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python +[http_response]: https://learn.microsoft.com/python/api/azure-core/azure.core.pipeline.transport.httpresponse?view=azure-python [azure_identity_pip]: https://pypi.org/project/azure-identity/ -[aad_authentication]: https://docs.microsoft.com/azure/cognitive-services/authentication?tabs=powershell#authenticate-with-an-authentication-token +[aad_authentication]: https://learn.microsoft.com/azure/cognitive-services/authentication?tabs=powershell#authenticate-with-an-authentication-token [identity_credentials]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity#credentials -[default_azure_credential]: https://docs.microsoft.com/python/api/azure-identity/azure.identity.defaultazurecredential?view=azure-python -[azure_key_credential]: https://docs.microsoft.com/python/api/azure-core/azure.core.credentials.azurekeycredential?view=azure-python -[bearer_token_credential_policy]: https://docs.microsoft.com/python/api/azure-core/azure.core.pipeline.policies.bearertokencredentialpolicy?view=azure-python -[azure_key_credential_policy]: https://docs.microsoft.com/python/api/azure-core/azure.core.pipeline.policies.azurekeycredentialpolicy?view=azure-python -[azure_core_exceptions]: https://docs.microsoft.com/python/api/azure-core/azure.core.exceptions?view=azure-python +[default_azure_credential]: https://learn.microsoft.com/python/api/azure-identity/azure.identity.defaultazurecredential?view=azure-python +[azure_key_credential]: https://learn.microsoft.com/python/api/azure-core/azure.core.credentials.azurekeycredential?view=azure-python +[bearer_token_credential_policy]: https://learn.microsoft.com/python/api/azure-core/azure.core.pipeline.policies.bearertokencredentialpolicy?view=azure-python +[azure_key_credential_policy]: https://learn.microsoft.com/python/api/azure-core/azure.core.pipeline.policies.azurekeycredentialpolicy?view=azure-python +[azure_core_exceptions]: https://learn.microsoft.com/python/api/azure-core/azure.core.exceptions?view=azure-python [azure_core_http_request]: https://azuresdkdocs.z19.web.core.windows.net/python/azure-core/latest/azure.core.html#azure.core.rest.HttpRequest [azure_core_http_response]: https://azuresdkdocs.z19.web.core.windows.net/python/azure-core/latest/azure.core.html#azure.core.rest.HttpResponse [azure_core_async_http_response]: https://azuresdkdocs.z19.web.core.windows.net/python/azure-core/latest/azure.core.html#azure.core.rest.AsyncHttpResponse