From 84d3b48a3802697aaf814debb0eb6252d0a7ff6d Mon Sep 17 00:00:00 2001
From: Yuchao Yan <yuchaoyan@microsoft.com>
Date: Wed, 10 Dec 2025 10:23:05 +0000
Subject: [PATCH 1/4] fix bad indent

---
 .../pygen/codegen/templates/macros.jinja2       | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

diff --git a/packages/http-client-python/generator/pygen/codegen/templates/macros.jinja2 b/packages/http-client-python/generator/pygen/codegen/templates/macros.jinja2
index 06868e5d6ab..e0033486cec 100644
--- a/packages/http-client-python/generator/pygen/codegen/templates/macros.jinja2
+++ b/packages/http-client-python/generator/pygen/codegen/templates/macros.jinja2
@@ -5,21 +5,28 @@
 {% set enable_custom_handling = "\n* " in doc_string or doc_string.startswith("* ") %}
 {%- if enable_custom_handling -%}
     {%- set lines = doc_string.split('\n') -%}
+    {%- set base_indent = wrap_string.lstrip('\n') -%}
     {%- set result_lines = [] -%}
     {%- for line in lines -%}
         {%- if line.startswith('* ') -%}
             {# Handle bullet points with proper continuation alignment #}
             {%- set bullet_content = line[2:] -%}
-            {%- set base_indent = wrap_string.lstrip('\n') -%}
             {%- set bullet_line = base_indent + ' * ' + bullet_content -%}
             {%- set continuation_spaces = base_indent + '   ' -%}
             {%- set wrapped = bullet_line | wordwrap(width=95, break_long_words=False, break_on_hyphens=False, wrapstring='\n' + continuation_spaces) -%}
             {%- set _ = result_lines.append(wrapped) -%}
         {%- elif line.strip() -%}
-            {%- set wrapped = line.strip() | wordwrap(width=95, break_long_words=False, break_on_hyphens=False, wrapstring=wrap_string) -%}
-            {%- set _ = result_lines.append(wrapped) -%}
+            {%- set line_indent = '' if line.strip().startswith(':') or loop.index == 1 else (base_indent + ' ') -%}
+            {%- set wrapped = (line_indent + line) | wordwrap(width=95, break_long_words=False, break_on_hyphens=False, wrapstring=wrap_string) -%}
+            {%- for line in wrapped.split('\n') -%}
+            {%- set prefix = "" if loop.index == 1 else " " -%}
+            {%- set _ = result_lines.append(prefix + line) -%}
+            {%- endfor -%}
         {%- else -%}
-            {%- set _ = result_lines.append('') -%}
+            {# Do not add continuous blank lines #}
+            {%- if (result_lines and result_lines[-1] != '') or not result_lines -%}
+              {%- set _ = result_lines.append('') -%}
+            {%- endif -%}
         {%- endif -%}
     {%- endfor -%}
     {%- set original_result = result_lines | join('\n') -%}
@@ -37,4 +44,4 @@
     {% set suffix = suffix_string if list_result | length == loop.index %}
 {{ prefix }}{{ line }}{{ suffix }}
 {% endfor %}
-{% endmacro %}
+{% endmacro %}
\ No newline at end of file

From 162fd1bb48c7d32993ab23c7c8ecb7cbffe7ef95 Mon Sep 17 00:00:00 2001
From: Yuchao Yan <yuchaoyan@microsoft.com>
Date: Wed, 10 Dec 2025 10:23:39 +0000
Subject: [PATCH 2/4] update

---
 .../changes/python-fix-docstring-2025-11-10-10-23-28.md    | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 .chronus/changes/python-fix-docstring-2025-11-10-10-23-28.md

diff --git a/.chronus/changes/python-fix-docstring-2025-11-10-10-23-28.md b/.chronus/changes/python-fix-docstring-2025-11-10-10-23-28.md
new file mode 100644
index 00000000000..6abfef34bc4
--- /dev/null
+++ b/.chronus/changes/python-fix-docstring-2025-11-10-10-23-28.md
@@ -0,0 +1,7 @@
+---
+changeKind: fix
+packages:
+  - "@typespec/http-client-python"
+---
+
+Fix bad indent
\ No newline at end of file

From 952ef7c90c15f54e7b62d2dbef26e7a69c039fee Mon Sep 17 00:00:00 2001
From: Yuchao Yan <yuchaoyan@microsoft.com>
Date: Wed, 10 Dec 2025 14:00:51 +0000
Subject: [PATCH 3/4] update

---
 .../eng/scripts/ci/regenerate.ts              |  6 +-
 .../generator/test/azure/requirements.txt     |  1 +
 .../test_specs_documentation_async.py         | 60 +++++++++++++++++++
 .../test_specs_documentation.py               | 52 ++++++++++++++++
 .../generator/test/unbranded/requirements.txt |  3 +-
 5 files changed, 120 insertions(+), 2 deletions(-)
 create mode 100644 packages/http-client-python/generator/test/generic_mock_api_tests/asynctests/test_specs_documentation_async.py
 create mode 100644 packages/http-client-python/generator/test/generic_mock_api_tests/test_specs_documentation.py

diff --git a/packages/http-client-python/eng/scripts/ci/regenerate.ts b/packages/http-client-python/eng/scripts/ci/regenerate.ts
index 5cb3c10b843..1e435969abf 100644
--- a/packages/http-client-python/eng/scripts/ci/regenerate.ts
+++ b/packages/http-client-python/eng/scripts/ci/regenerate.ts
@@ -22,7 +22,7 @@ const argv = parseArgs({
 });
 
 // Add this near the top with other constants
-const SKIP_SPECS = ["type/union/discriminated", "documentation"];
+const SKIP_SPECS = ["type/union/discriminated"];
 
 // Get the directory of the current file
 const PLUGIN_DIR = argv.values.pluginDir
@@ -272,6 +272,10 @@ const EMITTER_OPTIONS: Record<string, Record<string, string> | Record<string, st
     "package-name": "typetest-union",
     namespace: "typetest.union",
   },
+  documentation: {
+    "package-name": "specs-documentation",
+    namespace: "specs.documentation",
+  },
 };
 
 function toPosix(dir: string): string {
diff --git a/packages/http-client-python/generator/test/azure/requirements.txt b/packages/http-client-python/generator/test/azure/requirements.txt
index 9b22f8fd14f..30eb248fc7e 100644
--- a/packages/http-client-python/generator/test/azure/requirements.txt
+++ b/packages/http-client-python/generator/test/azure/requirements.txt
@@ -52,6 +52,7 @@ azure-mgmt-core==1.6.0
 -e ./generated/authentication-oauth2
 -e ./generated/authentication-union
 -e ./generated/setuppy-authentication-union
+-e ./generated/specs-documentation
 -e ./generated/encode-duration
 -e ./generated/encode-numeric
 -e ./generated/encode-array
diff --git a/packages/http-client-python/generator/test/generic_mock_api_tests/asynctests/test_specs_documentation_async.py b/packages/http-client-python/generator/test/generic_mock_api_tests/asynctests/test_specs_documentation_async.py
new file mode 100644
index 00000000000..a5abf91c3dd
--- /dev/null
+++ b/packages/http-client-python/generator/test/generic_mock_api_tests/asynctests/test_specs_documentation_async.py
@@ -0,0 +1,60 @@
+# -------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+
+import pytest
+from specs.documentation.aio import DocumentationClient
+from specs.documentation import models
+
+
+@pytest.fixture
+async def client():
+    async with DocumentationClient(endpoint="http://localhost:3000") as client:
+        yield client
+
+
+class TestLists:
+    @pytest.mark.asyncio
+    async def test_bullet_points_op(self, client: DocumentationClient):
+        # GET /documentation/lists/bullet-points/op
+        # Expected: 204 No Content
+        await client.lists.bullet_points_op()
+
+    @pytest.mark.skip(reason="https://github.com/microsoft/typespec/issues/9173")
+    @pytest.mark.asyncio
+    async def test_bullet_points_model(self, client: DocumentationClient):
+        # POST /documentation/lists/bullet-points/model
+        # Expected request body: {"prop": "Simple"}
+        # Expected: 200 OK
+        await client.lists.bullet_points_model(input=models.BulletPointsModel(prop="Simple"))
+
+        # Also test with JSON
+        await client.lists.bullet_points_model(body={"input": {"prop": "Simple"}})
+
+    @pytest.mark.asyncio
+    async def test_numbered(self, client: DocumentationClient):
+        # GET /documentation/lists/numbered
+        # Expected: 204 No Content
+        await client.lists.numbered()
+
+
+class TestTextFormatting:
+    @pytest.mark.asyncio
+    async def test_bold_text(self, client: DocumentationClient):
+        # GET /documentation/text-formatting/bold
+        # Expected: 204 No Content
+        await client.text_formatting.bold_text()
+
+    @pytest.mark.asyncio
+    async def test_italic_text(self, client: DocumentationClient):
+        # GET /documentation/text-formatting/italic
+        # Expected: 204 No Content
+        await client.text_formatting.italic_text()
+
+    @pytest.mark.asyncio
+    async def test_combined_formatting(self, client: DocumentationClient):
+        # GET /documentation/text-formatting/combined
+        # Expected: 204 No Content
+        await client.text_formatting.combined_formatting()
diff --git a/packages/http-client-python/generator/test/generic_mock_api_tests/test_specs_documentation.py b/packages/http-client-python/generator/test/generic_mock_api_tests/test_specs_documentation.py
new file mode 100644
index 00000000000..7d7a8cfefa8
--- /dev/null
+++ b/packages/http-client-python/generator/test/generic_mock_api_tests/test_specs_documentation.py
@@ -0,0 +1,52 @@
+# -------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+
+import pytest
+from specs.documentation import DocumentationClient, models
+
+
+@pytest.fixture
+def client():
+    with DocumentationClient(endpoint="http://localhost:3000") as client:
+        yield client
+
+
+class TestLists:
+    def test_bullet_points_op(self, client: DocumentationClient):
+        # GET /documentation/lists/bullet-points/op
+        # Expected: 204 No Content
+        client.lists.bullet_points_op()
+
+    @pytest.mark.skip(reason="https://github.com/microsoft/typespec/issues/9173")
+    def test_bullet_points_model(self, client: DocumentationClient):
+        # POST /documentation/lists/bullet-points/model
+        # Expected: 200 OK
+        client.lists.bullet_points_model(input=models.BulletPointsModel(prop="Simple"))
+
+        # Also test with JSON
+        client.lists.bullet_points_model(body={"input": {"prop": "Simple"}})
+
+    def test_numbered(self, client: DocumentationClient):
+        # GET /documentation/lists/numbered
+        # Expected: 204 No Content
+        client.lists.numbered()
+
+
+class TestTextFormatting:
+    def test_bold_text(self, client: DocumentationClient):
+        # GET /documentation/text-formatting/bold
+        # Expected: 204 No Content
+        client.text_formatting.bold_text()
+
+    def test_italic_text(self, client: DocumentationClient):
+        # GET /documentation/text-formatting/italic
+        # Expected: 204 No Content
+        client.text_formatting.italic_text()
+
+    def test_combined_formatting(self, client: DocumentationClient):
+        # GET /documentation/text-formatting/combined
+        # Expected: 204 No Content
+        client.text_formatting.combined_formatting()
diff --git a/packages/http-client-python/generator/test/unbranded/requirements.txt b/packages/http-client-python/generator/test/unbranded/requirements.txt
index 7a3dde49242..8bc015e9608 100644
--- a/packages/http-client-python/generator/test/unbranded/requirements.txt
+++ b/packages/http-client-python/generator/test/unbranded/requirements.txt
@@ -7,13 +7,14 @@
 -e ./generated/authentication-oauth2
 -e ./generated/authentication-union
 -e ./generated/setuppy-authentication-union
+-e ./generated/specs-documentation
 -e ./generated/encode-duration
 -e ./generated/encode-numeric
 -e ./generated/encode-array
 -e ./generated/parameters-basic
 -e ./generated/parameters-collection-format
 -e ./generated/parameters-path
--e ./generated/parameters-spread
+-e ./generated/parameters-spreadgit
 -e ./generated/serialization-encoded-name-json
 -e ./generated/server-endpoint-not-defined
 -e ./generated/server-path-multiple

From 8d098aa0e28edd7783951f0057767d45a6014148 Mon Sep 17 00:00:00 2001
From: Yuchao Yan <yuchaoyan@microsoft.com>
Date: Thu, 11 Dec 2025 02:02:42 +0000
Subject: [PATCH 4/4] fix ci

---
 .../generator/test/unbranded/requirements.txt                   | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/http-client-python/generator/test/unbranded/requirements.txt b/packages/http-client-python/generator/test/unbranded/requirements.txt
index 8bc015e9608..d788fe6b0d0 100644
--- a/packages/http-client-python/generator/test/unbranded/requirements.txt
+++ b/packages/http-client-python/generator/test/unbranded/requirements.txt
@@ -14,7 +14,7 @@
 -e ./generated/parameters-basic
 -e ./generated/parameters-collection-format
 -e ./generated/parameters-path
--e ./generated/parameters-spreadgit
+-e ./generated/parameters-spread
 -e ./generated/serialization-encoded-name-json
 -e ./generated/server-endpoint-not-defined
 -e ./generated/server-path-multiple