Add links to related sections of docs from docstrings

fastapi/applications.py

@@ -812,6 +812,9 @@ class FastAPI(Starlette):
 
                 In this case, there would be two different schemas, one for input and
                 another one for output.
+
+                Read more about it in the
+                [FastAPI docs about how to separate schemas for input and output](https://fastapi.tiangolo.com/how-to/separate-openapi-schemas)
                 """
             ),
         ] = True,

fastapi/exceptions.py

@@ -49,6 +49,9 @@ class HTTPException(StarletteHTTPException):
             Doc(
                 """
                 HTTP status code to send to the client.
+
+                Read more about it in the
+                [FastAPI docs for Handling Errors](https://fastapi.tiangolo.com/tutorial/handling-errors/#use-httpexception)
                 """
             ),
         ],
@@ -58,6 +61,9 @@ class HTTPException(StarletteHTTPException):
                 """
                 Any data to be sent to the client in the `detail` key of the JSON
                 response.
+
+                Read more about it in the
+                [FastAPI docs for Handling Errors](https://fastapi.tiangolo.com/tutorial/handling-errors/#use-httpexception)
                 """
             ),
         ] = None,
@@ -66,6 +72,10 @@ class HTTPException(StarletteHTTPException):
             Doc(
                 """
                 Any headers to send to the client in the response.
+
+                Read more about it in the
+                [FastAPI docs for Handling Errors](https://fastapi.tiangolo.com/tutorial/handling-errors/#add-custom-headers)
+
                 """
             ),
         ] = None,

fastapi/openapi/docs.py

@@ -33,6 +33,9 @@ def get_swagger_ui_html(
 
             This is normally done automatically by FastAPI using the default URL
             `/openapi.json`.
+
+            Read more about it in the
+            [FastAPI docs for Conditional OpenAPI](https://fastapi.tiangolo.com/how-to/conditional-openapi/#conditional-openapi-from-settings-and-env-vars)
             """
         ),
     ],
@@ -41,6 +44,9 @@ def get_swagger_ui_html(
         Doc(
             """
             The HTML `<title>` content, normally shown in the browser tab.
+
+            Read more about it in the
+            [FastAPI docs for Custom Docs UI Static Assets](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/)
             """
         ),
     ],
@@ -51,6 +57,9 @@ def get_swagger_ui_html(
             The URL to use to load the Swagger UI JavaScript.
 
             It is normally set to a CDN URL.
+
+            Read more about it in the
+            [FastAPI docs for Custom Docs UI Static Assets](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/)
             """
         ),
     ] = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js",
@@ -61,6 +70,9 @@ def get_swagger_ui_html(
             The URL to use to load the Swagger UI CSS.
 
             It is normally set to a CDN URL.
+
+            Read more about it in the
+            [FastAPI docs for Custom Docs UI Static Assets](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/)
             """
         ),
     ] = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css",
@@ -77,6 +89,9 @@ def get_swagger_ui_html(
         Doc(
             """
             The OAuth2 redirect URL, it is normally automatically handled by FastAPI.
+
+            Read more about it in the
+            [FastAPI docs for Custom Docs UI Static Assets](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/)
             """
         ),
     ] = None,
@@ -85,6 +100,9 @@ def get_swagger_ui_html(
         Doc(
             """
             A dictionary with Swagger UI OAuth2 initialization configurations.
+
+            Read more about the available configuration options in the
+            [Swagger UI docs](https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/).
             """
         ),
     ] = None,
@@ -95,6 +113,9 @@ def get_swagger_ui_html(
             Configuration parameters for Swagger UI.
 
             It defaults to [swagger_ui_default_parameters][fastapi.openapi.docs.swagger_ui_default_parameters].
+
+            Read more about it in the
+            [FastAPI docs about how to Configure Swagger UI](https://fastapi.tiangolo.com/how-to/configure-swagger-ui/).
             """
         ),
     ] = None,
@@ -168,6 +189,9 @@ def get_redoc_html(
 
             This is normally done automatically by FastAPI using the default URL
             `/openapi.json`.
+
+            Read more about it in the
+            [FastAPI docs for Conditional OpenAPI](https://fastapi.tiangolo.com/how-to/conditional-openapi/#conditional-openapi-from-settings-and-env-vars)
             """
         ),
     ],
@@ -176,6 +200,9 @@ def get_redoc_html(
         Doc(
             """
             The HTML `<title>` content, normally shown in the browser tab.
+
+            Read more about it in the
+            [FastAPI docs for Custom Docs UI Static Assets](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/)
             """
         ),
     ],
@@ -186,6 +213,9 @@ def get_redoc_html(
             The URL to use to load the ReDoc JavaScript.
 
             It is normally set to a CDN URL.
+
+            Read more about it in the
+            [FastAPI docs for Custom Docs UI Static Assets](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/)
             """
         ),
     ] = "https://cdn.jsdelivr.net/npm/redoc@2/bundles/redoc.standalone.js",

fastapi/param_functions.py

@@ -79,6 +79,9 @@ def Path(  # noqa: N802
         Doc(
             """
             Human-readable title.
+
+            Read more about it in the
+            [FastAPI docs for Path Parameters and Numeric Validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#declare-metadata)
             """
         ),
     ] = None,
@@ -96,6 +99,9 @@ def Path(  # noqa: N802
             """
             Greater than. If set, value must be greater than this. Only applicable to
             numbers.
+
+            Read more about it in the
+            [FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal)
             """
         ),
     ] = None,
@@ -105,6 +111,9 @@ def Path(  # noqa: N802
             """
             Greater than or equal. If set, value must be greater than or equal to
             this. Only applicable to numbers.
+
+            Read more about it in the
+            [FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal)
             """
         ),
     ] = None,
@@ -113,6 +122,9 @@ def Path(  # noqa: N802
         Doc(
             """
             Less than. If set, value must be less than this. Only applicable to numbers.
+
+            Read more about it in the
+            [FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal)
             """
         ),
     ] = None,
@@ -122,6 +134,9 @@ def Path(  # noqa: N802
             """
             Less than or equal. If set, value must be less than or equal to this.
             Only applicable to numbers.
+
+            Read more about it in the
+            [FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal)
             """
         ),
     ] = None,
@@ -213,6 +228,9 @@ def Path(  # noqa: N802
         Doc(
             """
             Example values for this field.
+
+            Read more about it in the
+            [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/)
             """
         ),
     ] = None,
@@ -343,6 +361,9 @@ def Query(  # noqa: N802
         Doc(
             """
             Default value if the parameter field is not set.
+
+            Read more about it in the
+            [FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#alternative-old-query-as-the-default-value)
             """
         ),
     ] = Undefined,
@@ -367,6 +388,9 @@ def Query(  # noqa: N802
             This will be used to extract the data and for the generated OpenAPI.
             It is particularly useful when you can't use the name you want because it
             is a Python reserved keyword or similar.
+
+            Read more about it in the
+            [FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#alias-parameters)
             """
         ),
     ] = None,
@@ -402,6 +426,9 @@ def Query(  # noqa: N802
         Doc(
             """
             Human-readable title.
+
+            Read more about it in the
+            [FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#declare-more-metadata)
             """
         ),
     ] = None,
@@ -410,6 +437,9 @@ def Query(  # noqa: N802
         Doc(
             """
             Human-readable description.
+
+            Read more about it in the
+            [FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#declare-more-metadata)
             """
         ),
     ] = None,
@@ -419,6 +449,9 @@ def Query(  # noqa: N802
             """
             Greater than. If set, value must be greater than this. Only applicable to
             numbers.
+
+            Read more about it in the
+            [FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal)
             """
         ),
     ] = None,
@@ -428,6 +461,9 @@ def Query(  # noqa: N802
             """
             Greater than or equal. If set, value must be greater than or equal to
             this. Only applicable to numbers.
+
+            Read more about it in the
+            [FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal)
             """
         ),
     ] = None,
@@ -436,6 +472,9 @@ def Query(  # noqa: N802
         Doc(
             """
             Less than. If set, value must be less than this. Only applicable to numbers.
+
+            Read more about it in the
+            [FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal)
             """
         ),
     ] = None,
@@ -445,6 +484,9 @@ def Query(  # noqa: N802
             """
             Less than or equal. If set, value must be less than or equal to this.
             Only applicable to numbers.
+
+            Read more about it in the
+            [FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal)
             """
         ),
     ] = None,
@@ -453,6 +495,9 @@ def Query(  # noqa: N802
         Doc(
             """
             Minimum length for strings.
+
+            Read more about it in the
+            [FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/)
             """
         ),
     ] = None,
@@ -461,6 +506,9 @@ def Query(  # noqa: N802
         Doc(
             """
             Maximum length for strings.
+
+            Read more about it in the
+            [FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/)
             """
         ),
     ] = None,
@@ -469,6 +517,9 @@ def Query(  # noqa: N802
         Doc(
             """
             RegEx pattern for strings.
+
+            Read more about it in the
+            [FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#add-regular-expressions
             """
         ),
     ] = None,
@@ -536,6 +587,9 @@ def Query(  # noqa: N802
         Doc(
             """
             Example values for this field.
+
+            Read more about it in the
+            [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/)
             """
         ),
     ] = None,
@@ -570,6 +624,9 @@ def Query(  # noqa: N802
             Mark this parameter field as deprecated.
 
             It will affect the generated OpenAPI (e.g. visible at `/docs`).
+
+            Read more about it in the
+            [FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#deprecating-parameters)
             """
         ),
     ] = None,
@@ -581,6 +638,9 @@ def Query(  # noqa: N802
             You probably don't need it, but it's available.
 
             This affects the generated OpenAPI (e.g. visible at `/docs`).
+
+            Read more about it in the
+            [FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi
             """
         ),
     ] = True,
@@ -849,6 +909,9 @@ def Header(  # noqa: N802
         Doc(
             """
             Example values for this field.
+
+            Read more about it in the
+            [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/)
             """
         ),
     ] = None,
@@ -1152,6 +1215,9 @@ def Cookie(  # noqa: N802
         Doc(
             """
             Example values for this field.
+
+            Read more about it in the
+            [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/)
             """
         ),
     ] = None,
@@ -1477,6 +1543,9 @@ def Body(  # noqa: N802
         Doc(
             """
             Example values for this field.
+
+            Read more about it in the
+            [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/)
             """
         ),
     ] = None,
@@ -1790,6 +1859,9 @@ def Form(  # noqa: N802
         Doc(
             """
             Example values for this field.
+
+            Read more about it in the
+            [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/)
             """
         ),
     ] = None,
@@ -2102,6 +2174,9 @@ def File(  # noqa: N802
         Doc(
             """
             Example values for this field.
+
+            Read more about it in the
+            [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/)
             """
         ),
     ] = None,
@@ -2215,6 +2290,9 @@ def Depends(  # noqa: N802
 
             Don't call it directly, FastAPI will call it for you, just pass the object
             directly.
+
+            Read more about it in the
+            [FastAPI docs for Dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/)
             """
         ),
     ] = None,
@@ -2230,6 +2308,9 @@ def Depends(  # noqa: N802
 
             Set `use_cache` to `False` to disable this behavior and ensure the
             dependency is called again (if declared more than once) in the same request.
+
+            Read more about it in the
+            [FastAPI docs about sub-dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/sub-dependencies/#using-the-same-dependency-multiple-times)
             """
         ),
     ] = True,
@@ -2250,6 +2331,9 @@ def Depends(  # noqa: N802
                 that handles the request (similar to when using `"function"`), but end
                 **after** the response is sent back to the client. So, the dependency
                 function will be executed **around** the **request** and response cycle.
+
+            Read more about it in the
+            [FastAPI docs for FastAPI Dependencies with yield](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-with-yield/#early-exit-and-scope)
             """
         ),
     ] = None,
@@ -2295,6 +2379,9 @@ def Security(  # noqa: N802
 
             Don't call it directly, FastAPI will call it for you, just pass the object
             directly.
+
+            Read more about it in the
+            [FastAPI docs for Dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/)
             """
         ),
     ] = None,
@@ -2312,7 +2399,9 @@ def Security(  # noqa: N802
 
             These scopes are integrated with OpenAPI (and the API docs at `/docs`).
             So they are visible in the OpenAPI specification.
-            )
+
+            Read more about it in the
+            [FastAPI docs about OAuth2 scopes](https://fastapi.tiangolo.com/advanced/security/oauth2-scopes/)
             """
         ),
     ] = None,
@@ -2327,6 +2416,9 @@ def Security(  # noqa: N802
 
             Set `use_cache` to `False` to disable this behavior and ensure the
             dependency is called again (if declared more than once) in the same request.
+
+            Read more about it in the
+            [FastAPI docs about sub-dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/sub-dependencies/#using-the-same-dependency-multiple-times)
             """
         ),
     ] = True,

fastapi/security/oauth2.py

@@ -68,6 +68,9 @@ class OAuth2PasswordRequestForm:
                 "password". Nevertheless, this dependency class is permissive and
                 allows not passing it. If you want to enforce it, use instead the
                 `OAuth2PasswordRequestFormStrict` dependency.
+
+                Read more about it in the
+                [FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/).
                 """
             ),
         ] = None,
@@ -78,6 +81,9 @@ class OAuth2PasswordRequestForm:
                 """
                 `username` string. The OAuth2 spec requires the exact field name
                 `username`.
+
+                Read more about it in the
+                [FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/).
                 """
             ),
         ],
@@ -88,6 +94,9 @@ class OAuth2PasswordRequestForm:
                 """
                 `password` string. The OAuth2 spec requires the exact field name
                 `password`.
+
+                Read more about it in the
+                [FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/).
                 """
             ),
         ],
@@ -112,6 +121,9 @@ class OAuth2PasswordRequestForm:
                 * `users:read`
                 * `profile`
                 * `openid`
+
+                Read more about it in the
+                [FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/).
                 """
             ),
         ] = "",
@@ -222,6 +234,9 @@ class OAuth2PasswordRequestFormStrict(OAuth2PasswordRequestForm):
                 "password". This dependency is strict about it. If you want to be
                 permissive, use instead the `OAuth2PasswordRequestForm` dependency
                 class.
+
+                Read more about it in the
+                [FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/).
                 """
             ),
         ],
@@ -232,6 +247,9 @@ class OAuth2PasswordRequestFormStrict(OAuth2PasswordRequestForm):
                 """
                 `username` string. The OAuth2 spec requires the exact field name
                 `username`.
+
+                Read more about it in the
+                [FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/).
                 """
             ),
         ],
@@ -242,6 +260,9 @@ class OAuth2PasswordRequestFormStrict(OAuth2PasswordRequestForm):
                 """
                 `password` string. The OAuth2 spec requires the exact field name
                 `password`.
+
+                Read more about it in the
+                [FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/).
                 """
             ),
         ],
@@ -266,6 +287,9 @@ class OAuth2PasswordRequestFormStrict(OAuth2PasswordRequestForm):
                 * `users:read`
                 * `profile`
                 * `openid`
+
+                Read more about it in the
+                [FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/).
                 """
             ),
         ] = "",
@@ -423,6 +447,9 @@ class OAuth2PasswordBearer(OAuth2):
                 """
                 The URL to obtain the OAuth2 token. This would be the *path operation*
                 that has `OAuth2PasswordRequestForm` as a dependency.
+
+                Read more about it in the
+                [FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/).
                 """
             ),
         ],
@@ -442,6 +469,9 @@ class OAuth2PasswordBearer(OAuth2):
                 """
                 The OAuth2 scopes that would be required by the *path operations* that
                 use this dependency.
+
+                Read more about it in the
+                [FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/).
                 """
             ),
         ] = None,