[Python] cleanup documentation (#15301)

* [Python] fix documentation of API authorization in README files fix hierarchy level + add internal links + align wording across generators * [Python] fix anchor links in documentation
OpenAPITools · May 9, 2023 · c251202 · c251202
1 parent da9ad4a
commit c251202
Show file tree

Hide file tree

Showing 55 changed files with 944 additions and 908 deletions.
diff --git a/modules/openapi-generator/src/main/resources/python-legacy/common_README.mustache b/modules/openapi-generator/src/main/resources/python-legacy/common_README.mustache
@@ -38,14 +38,14 @@ Class | Method | HTTP request | Description
 {{#models}}{{#model}} - [{{{classname}}}]({{modelDocPath}}{{{classname}}}.md)
 {{/model}}{{/models}}
 
+<a id="documentation-for-authorization"></a>
 ## Documentation For Authorization
 
-{{^authMethods}}
- All endpoints do not require authorization.
-{{/authMethods}}
+{{^authMethods}}Endpoints do not require authorization.{{/authMethods}}
+{{#hasAuthMethods}}Authentication schemes defined for the API:{{/hasAuthMethods}}
 {{#authMethods}}
-{{#last}} Authentication schemes defined for the API:{{/last}}
-## {{{name}}}
+<a id="{{name}}"></a>
+### {{{name}}}
 
 {{#isApiKey}}
 - **Type**: API key

diff --git a/modules/openapi-generator/src/main/resources/python-nextgen/common_README.mustache b/modules/openapi-generator/src/main/resources/python-nextgen/common_README.mustache
@@ -43,14 +43,14 @@ Class | Method | HTTP request | Description
 {{#models}}{{#model}} - [{{{classname}}}]({{modelDocPath}}{{{classname}}}.md)
 {{/model}}{{/models}}
 
+<a id="documentation-for-authorization"></a>
 ## Documentation For Authorization
 
-{{^authMethods}}
- All endpoints do not require authorization.
-{{/authMethods}}
+{{^authMethods}}Endpoints do not require authorization.{{/authMethods}}
+{{#hasAuthMethods}}Authentication schemes defined for the API:{{/hasAuthMethods}}
 {{#authMethods}}
-{{#last}} Authentication schemes defined for the API:{{/last}}
-## {{{name}}}
+<a id="{{name}}"></a>
+### {{{name}}}
 
 {{#isApiKey}}
 - **Type**: API key

diff --git a/modules/openapi-generator/src/main/resources/python-prior/README_common.mustache b/modules/openapi-generator/src/main/resources/python-prior/README_common.mustache
@@ -51,14 +51,14 @@ Class | Method | HTTP request | Description
 {{#models}}{{#model}} - [{{{classname}}}]({{modelDocPath}}{{{classname}}}.md)
 {{/model}}{{/models}}
 
+<a id="documentation-for-authorization"></a>
 ## Documentation For Authorization
 
-{{^authMethods}}
- All endpoints do not require authorization.
-{{/authMethods}}
+{{^authMethods}}Endpoints do not require authorization.{{/authMethods}}
+{{#hasAuthMethods}}Authentication schemes defined for the API:{{/hasAuthMethods}}
 {{#authMethods}}
-{{#last}} Authentication schemes defined for the API:{{/last}}
-## {{{name}}}
+<a id="{{name}}"></a>
+### {{{name}}}
 
 {{#isApiKey}}
 - **Type**: API key

diff --git a/modules/openapi-generator/src/main/resources/python/README_common.handlebars b/modules/openapi-generator/src/main/resources/python/README_common.handlebars
@@ -53,11 +53,12 @@ Class | Method | HTTP request | Description
 ## Documentation For Authorization
 
 {{#unless authMethods}}
- All endpoints do not require authorization.
+ Endpoints do not require authorization.
 {{/unless}}
+{{#if hasAuthMethods}}Authentication schemes defined for the API:{{/if}}
 {{#each authMethods}}
-{{#if @last}} Authentication schemes defined for the API:{{/if}}
-## {{{name}}}
+<a id="{{name}}"></a>
+### {{{name}}}
 
 {{#if isApiKey}}
 - **Type**: API key

diff --git a/modules/openapi-generator/src/main/resources/python/api_doc.handlebars b/modules/openapi-generator/src/main/resources/python/api_doc.handlebars
@@ -1,4 +1,4 @@
-<a name="__pageTop"></a>
+<a id="__pageTop"></a>
 # {{packageName}}.{{apiPackage}}.tags.{{classFilename}}.{{classname}}{{#if description}}
 {{description}}{{/if}}
 
@@ -12,7 +12,7 @@ Method | HTTP request | Description
 {{#with operations}}
 {{#each operation}}
 # **{{{operationId}}}**
-<a name="{{{operationId}}}"></a>
+<a id="{{{operationId}}}"></a>
 > {{#if returnType}}{{{returnType}}} {{/if}}{{{operationId}}}({{#each requiredParams}}{{#unless defaultValue}}{{paramName}}{{#if hasMore}}, {{/if}}{{/unless}}{{/each}})
 
 {{#if summary}}{{{summary}}}{{/if}}{{#if notes}}

diff --git a/samples/client/echo_api/python-nextgen/README.md b/samples/client/echo_api/python-nextgen/README.md
@@ -119,9 +119,11 @@ Class | Method | HTTP request | Description
  - [TestQueryStyleFormExplodeTrueArrayStringQueryObjectParameter](docs/TestQueryStyleFormExplodeTrueArrayStringQueryObjectParameter.md)
 
 
+<a id="documentation-for-authorization"></a>
 ## Documentation For Authorization
 
- All endpoints do not require authorization.
+Endpoints do not require authorization.
+
 
 ## Author
 

diff --git a/samples/client/petstore/python-asyncio/README.md b/samples/client/petstore/python-asyncio/README.md
@@ -172,10 +172,13 @@ Class | Method | HTTP request | Description
  - [XmlItem](docs/XmlItem.md)
 
 
+<a id="documentation-for-authorization"></a>
 ## Documentation For Authorization
 
 
-## petstore_auth
+Authentication schemes defined for the API:
+<a id="petstore_auth"></a>
+### petstore_auth
 
 - **Type**: OAuth
 - **Flow**: implicit
@@ -184,22 +187,22 @@ Class | Method | HTTP request | Description
  - **write:pets**: modify pets in your account
  - **read:pets**: read your pets
 
-
-## api_key
+<a id="api_key"></a>
+### api_key
 
 - **Type**: API key
 - **API key parameter name**: api_key
 - **Location**: HTTP header
 
-
-## api_key_query
+<a id="api_key_query"></a>
+### api_key_query
 
 - **Type**: API key
 - **API key parameter name**: api_key_query
 - **Location**: URL query string
 
-
-## http_basic_test
+<a id="http_basic_test"></a>
+### http_basic_test
 
 - **Type**: HTTP basic authentication
 

diff --git a/samples/client/petstore/python-legacy/README.md b/samples/client/petstore/python-legacy/README.md
@@ -172,10 +172,13 @@ Class | Method | HTTP request | Description
  - [XmlItem](docs/XmlItem.md)
 
 
+<a id="documentation-for-authorization"></a>
 ## Documentation For Authorization
 
 
-## petstore_auth
+Authentication schemes defined for the API:
+<a id="petstore_auth"></a>
+### petstore_auth
 
 - **Type**: OAuth
 - **Flow**: implicit
@@ -184,22 +187,22 @@ Class | Method | HTTP request | Description
  - **write:pets**: modify pets in your account
  - **read:pets**: read your pets
 
-
-## api_key
+<a id="api_key"></a>
+### api_key
 
 - **Type**: API key
 - **API key parameter name**: api_key
 - **Location**: HTTP header
 
-
-## api_key_query
+<a id="api_key_query"></a>
+### api_key_query
 
 - **Type**: API key
 - **API key parameter name**: api_key_query
 - **Location**: URL query string
 
-
-## http_basic_test
+<a id="http_basic_test"></a>
+### http_basic_test
 
 - **Type**: HTTP basic authentication
 

diff --git a/samples/client/petstore/python-prior/README.md b/samples/client/petstore/python-prior/README.md
@@ -196,10 +196,13 @@ Class | Method | HTTP request | Description
  - [XmlItem](docs/XmlItem.md)
 
 
+<a id="documentation-for-authorization"></a>
 ## Documentation For Authorization
 
 
-## petstore_auth
+Authentication schemes defined for the API:
+<a id="petstore_auth"></a>
+### petstore_auth
 
 - **Type**: OAuth
 - **Flow**: implicit
@@ -208,22 +211,22 @@ Class | Method | HTTP request | Description
  - **write:pets**: modify pets in your account
  - **read:pets**: read your pets
 
-
-## api_key
+<a id="api_key"></a>
+### api_key
 
 - **Type**: API key
 - **API key parameter name**: api_key
 - **Location**: HTTP header
 
-
-## api_key_query
+<a id="api_key_query"></a>
+### api_key_query
 
 - **Type**: API key
 - **API key parameter name**: api_key_query
 - **Location**: URL query string
 
-
-## http_basic_test
+<a id="http_basic_test"></a>
+### http_basic_test
 
 - **Type**: HTTP basic authentication
 

diff --git a/...client/petstore/python-prior_disallowAdditionalPropertiesIfNotPresent/README.md b/...client/petstore/python-prior_disallowAdditionalPropertiesIfNotPresent/README.md
@@ -196,10 +196,13 @@ Class | Method | HTTP request | Description
  - [XmlItem](docs/XmlItem.md)
 
 
+<a id="documentation-for-authorization"></a>
 ## Documentation For Authorization
 
 
-## petstore_auth
+Authentication schemes defined for the API:
+<a id="petstore_auth"></a>
+### petstore_auth
 
 - **Type**: OAuth
 - **Flow**: implicit
@@ -208,22 +211,22 @@ Class | Method | HTTP request | Description
  - **write:pets**: modify pets in your account
  - **read:pets**: read your pets
 
-
-## api_key
+<a id="api_key"></a>
+### api_key
 
 - **Type**: API key
 - **API key parameter name**: api_key
 - **Location**: HTTP header
 
-
-## api_key_query
+<a id="api_key_query"></a>
+### api_key_query
 
 - **Type**: API key
 - **API key parameter name**: api_key_query
 - **Location**: URL query string
 
-
-## http_basic_test
+<a id="http_basic_test"></a>
+### http_basic_test
 
 - **Type**: HTTP basic authentication
 

diff --git a/samples/client/petstore/python-tornado/README.md b/samples/client/petstore/python-tornado/README.md
@@ -172,10 +172,13 @@ Class | Method | HTTP request | Description
  - [XmlItem](docs/XmlItem.md)
 
 
+<a id="documentation-for-authorization"></a>
 ## Documentation For Authorization
 
 
-## petstore_auth
+Authentication schemes defined for the API:
+<a id="petstore_auth"></a>
+### petstore_auth
 
 - **Type**: OAuth
 - **Flow**: implicit
@@ -184,22 +187,22 @@ Class | Method | HTTP request | Description
  - **write:pets**: modify pets in your account
  - **read:pets**: read your pets
 
-
-## api_key
+<a id="api_key"></a>
+### api_key
 
 - **Type**: API key
 - **API key parameter name**: api_key
 - **Location**: HTTP header
 
-
-## api_key_query
+<a id="api_key_query"></a>
+### api_key_query
 
 - **Type**: API key
 - **API key parameter name**: api_key_query
 - **Location**: URL query string
 
-
-## http_basic_test
+<a id="http_basic_test"></a>
+### http_basic_test
 
 - **Type**: HTTP basic authentication
 

diff --git a/samples/openapi3/client/3_0_3_unit_test/python/README.md b/samples/openapi3/client/3_0_3_unit_test/python/README.md
@@ -961,7 +961,8 @@ Class | Method | HTTP request | Description
 
 ## Documentation For Authorization
 
- All endpoints do not require authorization.
+ Endpoints do not require authorization.
+
 
 ## Author