[Doc] Refine constants in doc string (#2846)

# Description Please add an informative description that covers that changes made by the pull request and link all relevant issues. # All Promptflow Contribution checklist: - [ ] **The pull request does not introduce [breaking changes].** - [ ] **CHANGELOG is updated for new features, bug fixes or other significant changes.** - [ ] **I have read the [contribution guidelines](../CONTRIBUTING.md).** - [ ] **Create an issue and link to the pull request to get dedicated review from promptflow team. Learn more: [suggested workflow](../CONTRIBUTING.md#suggested-workflow).** ## General Guidelines and Best Practices - [ ] Title of the pull request is clear and informative. - [ ] There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For more information on cleaning up the commits in your PR, [see this page](https://github.com/Azure/azure-powershell/blob/master/documentation/development-docs/cleaning-up-commits.md). ### Testing Guidelines - [ ] Pull request includes test coverage for the included changes. Signed-off-by: Brynn Yin <[email protected]>
microsoft · Apr 17, 2024 · 6a6434f · 6a6434f
1 parent 837111d
commit 6a6434f
Show file tree

Hide file tree

Showing 12 changed files with 43 additions and 40 deletions.
diff --git a/docs/how-to-guides/develop-a-flow/index.md b/docs/how-to-guides/develop-a-flow/index.md
@@ -3,7 +3,6 @@ We provide guides on how to develop a flow by writing a flow yaml from scratch i
 
 ```{toctree}
 :maxdepth: 1
-:hidden:
 
 init-and-test-a-flow
 develop-standard-flow

diff --git a/scripts/docs/api_doc_templates/package.rst_t b/scripts/docs/api_doc_templates/package.rst_t
@@ -16,7 +16,7 @@
 {%- if is_namespace %}
 {{- [pkgname, "namespace"] | join(" ") | e | heading }}
 {% else %}
-{{- [pkgname, ""] | join(" ") | e | heading }}
+{{- [pkgname, "module"] | join(" ") | e | heading }}
 {% endif %}
 
 {%- if is_namespace %}

diff --git a/scripts/docs/doc_generation.ps1 b/scripts/docs/doc_generation.ps1
@@ -110,7 +110,7 @@ if($WithReferenceDoc){
         $SubPkgRefDocPath = [System.IO.Path]::Combine($RefDocPath, $Item.Name)
         Write-Host "===============Build $Item Reference Doc==============="
         $TemplatePath = [System.IO.Path]::Combine($RepoRootPath, "scripts\docs\api_doc_templates")
-        sphinx-apidoc --module-first --no-headings --no-toc --implicit-namespaces "$SubPkgPath" -o "$SubPkgRefDocPath" -t $TemplatePath | Tee-Object -FilePath $SphinxApiDoc
+        sphinx-apidoc --separate --module-first --no-toc --implicit-namespaces "$SubPkgPath" -o "$SubPkgRefDocPath" -t $TemplatePath | Tee-Object -FilePath $SphinxApiDoc
         $SubPkgWarningsAndErrors = Select-String -Path $SphinxApiDoc -Pattern $WarningErrorPattern
         if($SubPkgWarningsAndErrors){
             $ApidocWarningsAndErrors.AddRange($SubPkgWarningsAndErrors)

diff --git a/src/promptflow-core/promptflow/_constants.py b/src/promptflow-core/promptflow/_constants.py
@@ -236,18 +236,6 @@ class ConnectionType(str, Enum):
     CUSTOM = "Custom"
 
 
-class ConnectionAuthMode:
-    KEY = "key"
-    MEID_TOKEN = "meid_token"  # Microsoft Entra ID
-
-
-class ConnectionDefaultApiVersion:
-    AZURE_OPEN_AI = "2024-02-01"
-    COGNITIVE_SEARCH = "2023-11-01"
-    AZURE_CONTENT_SAFETY = "2023-10-01"
-    FORM_RECOGNIZER = "2023-07-31"
-
-
 class CustomStrongTypeConnectionConfigs:
     PREFIX = "promptflow.connection."
     TYPE = "custom_type"

diff --git a/src/promptflow-core/promptflow/constants.py b/src/promptflow-core/promptflow/constants.py
@@ -0,0 +1,19 @@
+# ---------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# ---------------------------------------------------------
+
+
+class ConnectionAuthMode:
+    """Promptflow connection auth_mode values."""
+
+    KEY = "key"
+    MEID_TOKEN = "meid_token"  # Microsoft Entra ID
+
+
+class ConnectionDefaultApiVersion:
+    """Promptflow connection default api version values."""
+
+    AZURE_OPEN_AI = "2024-02-01"
+    COGNITIVE_SEARCH = "2023-11-01"
+    AZURE_CONTENT_SAFETY = "2023-10-01"
+    FORM_RECOGNIZER = "2023-07-31"
diff --git a/src/promptflow-core/promptflow/core/_connection.py b/src/promptflow-core/promptflow/core/_connection.py
@@ -7,16 +7,11 @@
 from typing import Dict, List
 
 from promptflow._constants import CONNECTION_SCRUBBED_VALUE as SCRUBBED_VALUE
-from promptflow._constants import (
-    CONNECTION_SCRUBBED_VALUE_NO_CHANGE,
-    ConnectionAuthMode,
-    ConnectionDefaultApiVersion,
-    ConnectionType,
-    CustomStrongTypeConnectionConfigs,
-)
+from promptflow._constants import CONNECTION_SCRUBBED_VALUE_NO_CHANGE, ConnectionType, CustomStrongTypeConnectionConfigs
 from promptflow._core.token_provider import AzureTokenProvider
 from promptflow._utils.logger_utils import LoggerFactory
 from promptflow._utils.utils import in_jupyter_notebook
+from promptflow.constants import ConnectionAuthMode, ConnectionDefaultApiVersion
 from promptflow.contracts.types import Secret
 from promptflow.core._errors import RequiredEnvironmentVariablesNotSetError
 from promptflow.exceptions import UserErrorException, ValidationException
@@ -156,9 +151,9 @@ class AzureOpenAIConnection(_StrongTypeConnection):
     :type api_base: str
     :param api_type: The api type, default "azure".
     :type api_type: str
-    :param api_version: The api version, default ${ConnectionDefaultApiVersion.AZURE_OPEN_AI}.
+    :param api_version: The api version, default see: :obj:`~.constants.ConnectionDefaultApiVersion.AZURE_OPEN_AI`
     :type api_version: str
-    :param auth_mode: The auth mode, supported value ["key", "meid_token"].
+    :param auth_mode: The auth mode, supported values see: :class:`~.constants.ConnectionAuthMode`.
     :type auth_mode: str
     :param name: Connection name.
     :type name: str
@@ -238,9 +233,12 @@ def from_env(cls, name=None):
         Build connection from environment variables.
 
         Relevant environment variables:
-        - AZURE_OPENAI_ENDPOINT: The api base.
-        - AZURE_OPENAI_API_KEY: The api key.
-        - OPENAI_API_VERSION: Optional. The api version, default ${ConnectionDefaultApiVersion.AZURE_OPEN_AI}.
+         - AZURE_OPENAI_ENDPOINT: The api base.
+         - AZURE_OPENAI_API_KEY: The api key.
+         - OPENAI_API_VERSION: Optional.
+
+         The api version default to :obj:`~.constants.ConnectionDefaultApiVersion.AZURE_OPEN_AI`.
+
         """
         # Env var name reference: https://github.com/openai/openai-python/blob/main/src/openai/lib/azure.py#L160
         api_base = os.getenv("AZURE_OPENAI_ENDPOINT")
@@ -458,7 +456,8 @@ class AzureContentSafetyConnection(_StrongTypeConnection):
     :type api_key: str
     :param endpoint: The api endpoint.
     :type endpoint: str
-    :param api_version: The api version, default ${ConnectionDefaultApiVersion.AZURE_CONTENT_SAFETY}.
+    :param api_version: The api version,
+        default see: :obj:`~.constants.ConnectionDefaultApiVersion.AZURE_CONTENT_SAFETY`.
     :type api_version: str
     :param api_type: The api type, default "Content Safety".
     :type api_type: str
@@ -518,7 +517,7 @@ class FormRecognizerConnection(AzureContentSafetyConnection):
     :type api_key: str
     :param endpoint: The api endpoint.
     :type endpoint: str
-    :param api_version: The api version, default ${ConnectionDefaultApiVersion.FORM_RECOGNIZER}.
+    :param api_version: The api version, default see: :obj:`~.constants.ConnectionDefaultApiVersion.FORM_RECOGNIZER`.
     :type api_version: str
     :param api_type: The api type, default "Form Recognizer".
     :type api_type: str

diff --git a/src/promptflow-core/promptflow/core/_connection_provider/_workspace_connection_provider.py b/src/promptflow-core/promptflow/core/_connection_provider/_workspace_connection_provider.py
@@ -6,8 +6,9 @@
 
 import requests
 
-from promptflow._constants import AML_WORKSPACE_TEMPLATE, ConnectionAuthMode
+from promptflow._constants import AML_WORKSPACE_TEMPLATE
 from promptflow._utils.retry_utils import http_retry_wrapper
+from promptflow.constants import ConnectionAuthMode
 from promptflow.core._connection import CustomConnection, _Connection
 from promptflow.core._errors import (
     AccessDeniedError,

diff --git a/src/promptflow-core/tests/azureml-serving/unittests/test_workspace_connection_provider.py b/src/promptflow-core/tests/azureml-serving/unittests/test_workspace_connection_provider.py
@@ -5,7 +5,7 @@
 
 import pytest
 
-from promptflow._constants import ConnectionAuthMode
+from promptflow.constants import ConnectionAuthMode
 from promptflow.core._connection_provider._models._models import (
     WorkspaceConnectionPropertiesV2BasicResource,
     WorkspaceConnectionPropertiesV2BasicResourceArmPaginatedResult,

diff --git a/src/promptflow-devkit/promptflow/_sdk/_constants.py b/src/promptflow-devkit/promptflow/_sdk/_constants.py
@@ -12,10 +12,10 @@
     CONNECTION_SCRUBBED_VALUE,
     CONNECTION_SCRUBBED_VALUE_NO_CHANGE,
     PROMPT_FLOW_DIR_NAME,
-    ConnectionAuthMode,
     ConnectionType,
     CustomStrongTypeConnectionConfigs,
 )
+from promptflow.constants import ConnectionAuthMode
 
 LOGGER_NAME = "promptflow"
 

diff --git a/src/promptflow-devkit/promptflow/_sdk/schemas/_connection.py b/src/promptflow-devkit/promptflow/_sdk/schemas/_connection.py
@@ -5,16 +5,12 @@
 
 from marshmallow import ValidationError, fields, post_load, pre_dump, validates
 
-from promptflow._constants import (
-    ConnectionAuthMode,
-    ConnectionDefaultApiVersion,
-    ConnectionType,
-    CustomStrongTypeConnectionConfigs,
-)
+from promptflow._constants import ConnectionType, CustomStrongTypeConnectionConfigs
 from promptflow._sdk._constants import SCHEMA_KEYS_CONTEXT_CONFIG_KEY, SCHEMA_KEYS_CONTEXT_SECRET_KEY
 from promptflow._sdk.schemas._base import YamlFileSchema
 from promptflow._sdk.schemas._fields import StringTransformedEnum
 from promptflow._utils.utils import camel_to_snake
+from promptflow.constants import ConnectionAuthMode, ConnectionDefaultApiVersion
 
 
 class ConnectionSchema(YamlFileSchema):

diff --git a/src/promptflow-devkit/tests/sdk_cli_test/e2etests/test_connection.py b/src/promptflow-devkit/tests/sdk_cli_test/e2etests/test_connection.py
@@ -6,11 +6,11 @@
 from _constants import PROMPTFLOW_ROOT
 from mock import mock
 
-from promptflow._constants import ConnectionDefaultApiVersion
 from promptflow._sdk._constants import SCRUBBED_VALUE
 from promptflow._sdk._errors import ConnectionNameNotSetError
 from promptflow._sdk._pf_client import PFClient
 from promptflow._sdk.entities import AzureOpenAIConnection, CustomConnection, OpenAIConnection
+from promptflow.constants import ConnectionDefaultApiVersion
 
 TEST_ROOT = PROMPTFLOW_ROOT / "tests"
 CONNECTION_ROOT = TEST_ROOT / "test_configs/connections"

diff --git a/src/promptflow-devkit/tests/sdk_cli_test/unittests/test_connection.py b/src/promptflow-devkit/tests/sdk_cli_test/unittests/test_connection.py
@@ -9,7 +9,7 @@
 from _constants import PROMPTFLOW_ROOT
 
 from promptflow._cli._pf._connection import validate_and_interactive_get_secrets
-from promptflow._sdk._constants import SCRUBBED_VALUE, ConnectionAuthMode, CustomStrongTypeConnectionConfigs
+from promptflow._sdk._constants import SCRUBBED_VALUE, CustomStrongTypeConnectionConfigs
 from promptflow._sdk._errors import ConnectionClassNotFoundError, SDKError
 from promptflow._sdk._load_functions import _load_env_to_connection
 from promptflow._sdk.entities._connection import (
@@ -26,6 +26,7 @@
     _Connection,
 )
 from promptflow._utils.yaml_utils import load_yaml
+from promptflow.constants import ConnectionAuthMode
 from promptflow.core._connection import RequiredEnvironmentVariablesNotSetError
 from promptflow.exceptions import UserErrorException