From 47851b1560a4274f0ede99506a50dea98538092c Mon Sep 17 00:00:00 2001 From: Anuraag Agrawal Date: Fri, 15 Aug 2025 12:15:23 +0900 Subject: [PATCH 1/3] Migrate API docs to mkdocstrings --- docs/api.md | 51 ++++++++++++++++++------ docs/css/custom.css | 8 ++++ mkdocs.yml | 96 +++++++++++++++++++++++++-------------------- requirements.txt | 2 +- 4 files changed, 100 insertions(+), 57 deletions(-) diff --git a/docs/api.md b/docs/api.md index f1bd50c993..bde7cd75a1 100644 --- a/docs/api.md +++ b/docs/api.md @@ -9,43 +9,68 @@ long-lived connections. ::: httpx.request - :docstring: ::: httpx.get - :docstring: ::: httpx.options - :docstring: ::: httpx.head - :docstring: ::: httpx.post - :docstring: ::: httpx.put - :docstring: ::: httpx.patch - :docstring: ::: httpx.delete - :docstring: ::: httpx.stream - :docstring: ## `Client` ::: httpx.Client - :docstring: - :members: headers cookies params auth request get head options post put patch delete stream build_request send close + options: + inherited_members: true + members: + - headers + - cookies + - params + - auth + - request + - get + - head + - options + - post + - put + - patch + - delete + - stream + - build_request + - send + - close ## `AsyncClient` ::: httpx.AsyncClient - :docstring: - :members: headers cookies params auth request get head options post put patch delete stream build_request send aclose + inherited_members: true + options: + members: + - headers + - cookies + - params + - auth + - request + - get + - head + - options + - post + - put + - patch + - delete + - stream + - build_request + - send + - aclose ## `Response` diff --git a/docs/css/custom.css b/docs/css/custom.css index 6e5d919192..60a468b9ab 100644 --- a/docs/css/custom.css +++ b/docs/css/custom.css @@ -8,3 +8,11 @@ div.autodoc-members { padding-left: 20px; margin-bottom: 15px; } + +.doc-class-bases { + display: none; +} + +div[data-md-type="toc"] .md-nav__item > .md-nav { + display: none; +} diff --git a/mkdocs.yml b/mkdocs.yml index 86ca1e53b7..38caf2dc05 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -3,59 +3,69 @@ site_description: A next-generation HTTP client for Python. site_url: https://www.python-httpx.org/ theme: - name: 'material' - custom_dir: 'docs/overrides' - palette: - - scheme: 'default' - media: '(prefers-color-scheme: light)' - toggle: - icon: 'material/lightbulb' - name: "Switch to dark mode" - - scheme: 'slate' - media: '(prefers-color-scheme: dark)' - primary: 'blue' - toggle: - icon: 'material/lightbulb-outline' - name: 'Switch to light mode' + name: "material" + custom_dir: "docs/overrides" + palette: + - scheme: "default" + media: "(prefers-color-scheme: light)" + toggle: + icon: "material/lightbulb" + name: "Switch to dark mode" + - scheme: "slate" + media: "(prefers-color-scheme: dark)" + primary: "blue" + toggle: + icon: "material/lightbulb-outline" + name: "Switch to light mode" repo_name: encode/httpx repo_url: https://github.com/encode/httpx/ edit_uri: "" nav: - - Introduction: 'index.md' - - QuickStart: 'quickstart.md' - - Advanced: - - Clients: 'advanced/clients.md' - - Authentication: 'advanced/authentication.md' - - SSL: 'advanced/ssl.md' - - Proxies: 'advanced/proxies.md' - - Timeouts: 'advanced/timeouts.md' - - Resource Limits: 'advanced/resource-limits.md' - - Event Hooks: 'advanced/event-hooks.md' - - Transports: 'advanced/transports.md' - - Text Encodings: 'advanced/text-encodings.md' - - Extensions: 'advanced/extensions.md' - - Guides: - - Async Support: 'async.md' - - HTTP/2 Support: 'http2.md' - - Logging: 'logging.md' - - Requests Compatibility: 'compatibility.md' - - Troubleshooting: 'troubleshooting.md' - - API Reference: - - Developer Interface: 'api.md' - - Exceptions: 'exceptions.md' - - Environment Variables: 'environment_variables.md' - - Community: - - Third Party Packages: 'third_party_packages.md' - - Contributing: 'contributing.md' - - Code of Conduct: 'code_of_conduct.md' + - Introduction: "index.md" + - QuickStart: "quickstart.md" + - Advanced: + - Clients: "advanced/clients.md" + - Authentication: "advanced/authentication.md" + - SSL: "advanced/ssl.md" + - Proxies: "advanced/proxies.md" + - Timeouts: "advanced/timeouts.md" + - Resource Limits: "advanced/resource-limits.md" + - Event Hooks: "advanced/event-hooks.md" + - Transports: "advanced/transports.md" + - Text Encodings: "advanced/text-encodings.md" + - Extensions: "advanced/extensions.md" + - Guides: + - Async Support: "async.md" + - HTTP/2 Support: "http2.md" + - Logging: "logging.md" + - Requests Compatibility: "compatibility.md" + - Troubleshooting: "troubleshooting.md" + - API Reference: + - Developer Interface: "api.md" + - Exceptions: "exceptions.md" + - Environment Variables: "environment_variables.md" + - Community: + - Third Party Packages: "third_party_packages.md" + - Contributing: "contributing.md" + - Code of Conduct: "code_of_conduct.md" + +plugins: + - mkdocstrings: + handlers: + python: + options: + merge_init_into_class: true + show_root_heading: true + heading_level: 3 + inventories: + - https://docs.python.org/3/objects.inv markdown_extensions: - admonition - codehilite: css_class: highlight - - mkautodoc extra_css: - - css/custom.css + - css/custom.css diff --git a/requirements.txt b/requirements.txt index 646cb813d7..7e0d9a9b14 100644 --- a/requirements.txt +++ b/requirements.txt @@ -10,7 +10,7 @@ chardet==5.2.0 # Documentation mkdocs==1.6.1 -mkautodoc==0.2.0 +mkdocstrings[python]==0.30.0 mkdocs-material==9.5.47 # Packaging From 44259644128126c8661f546227313c3b1ad003f4 Mon Sep 17 00:00:00 2001 From: Anuraag Agrawal Date: Fri, 15 Aug 2025 12:16:21 +0900 Subject: [PATCH 2/3] Drift --- mkdocs.yml | 70 +++++++++++++++++++++++++++--------------------------- 1 file changed, 35 insertions(+), 35 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 38caf2dc05..3bbe322591 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -3,53 +3,53 @@ site_description: A next-generation HTTP client for Python. site_url: https://www.python-httpx.org/ theme: - name: "material" - custom_dir: "docs/overrides" + name: 'material' + custom_dir: 'docs/overrides' palette: - - scheme: "default" - media: "(prefers-color-scheme: light)" + - scheme: 'default' + media: '(prefers-color-scheme: light)' toggle: - icon: "material/lightbulb" - name: "Switch to dark mode" - - scheme: "slate" - media: "(prefers-color-scheme: dark)" - primary: "blue" + icon: 'material/lightbulb' + name: 'Switch to dark mode' + - scheme: 'slate' + media: '(prefers-color-scheme: dark)' + primary: 'blue' toggle: - icon: "material/lightbulb-outline" - name: "Switch to light mode" + icon: 'material/lightbulb-outline' + name: 'Switch to light mode' repo_name: encode/httpx repo_url: https://github.com/encode/httpx/ -edit_uri: "" +edit_uri: '' nav: - - Introduction: "index.md" - - QuickStart: "quickstart.md" + - Introduction: 'index.md' + - QuickStart: 'quickstart.md' - Advanced: - - Clients: "advanced/clients.md" - - Authentication: "advanced/authentication.md" - - SSL: "advanced/ssl.md" - - Proxies: "advanced/proxies.md" - - Timeouts: "advanced/timeouts.md" - - Resource Limits: "advanced/resource-limits.md" - - Event Hooks: "advanced/event-hooks.md" - - Transports: "advanced/transports.md" - - Text Encodings: "advanced/text-encodings.md" - - Extensions: "advanced/extensions.md" + - Clients: 'advanced/clients.md' + - Authentication: 'advanced/authentication.md' + - SSL: 'advanced/ssl.md' + - Proxies: 'advanced/proxies.md' + - Timeouts: 'advanced/timeouts.md' + - Resource Limits: 'advanced/resource-limits.md' + - Event Hooks: 'advanced/event-hooks.md' + - Transports: 'advanced/transports.md' + - Text Encodings: 'advanced/text-encodings.md' + - Extensions: 'advanced/extensions.md' - Guides: - - Async Support: "async.md" - - HTTP/2 Support: "http2.md" - - Logging: "logging.md" - - Requests Compatibility: "compatibility.md" - - Troubleshooting: "troubleshooting.md" + - Async Support: 'async.md' + - HTTP/2 Support: 'http2.md' + - Logging: 'logging.md' + - Requests Compatibility: 'compatibility.md' + - Troubleshooting: 'troubleshooting.md' - API Reference: - - Developer Interface: "api.md" - - Exceptions: "exceptions.md" - - Environment Variables: "environment_variables.md" + - Developer Interface: 'api.md' + - Exceptions: 'exceptions.md' + - Environment Variables: 'environment_variables.md' - Community: - - Third Party Packages: "third_party_packages.md" - - Contributing: "contributing.md" - - Code of Conduct: "code_of_conduct.md" + - Third Party Packages: 'third_party_packages.md' + - Contributing: 'contributing.md' + - Code of Conduct: 'code_of_conduct.md' plugins: - mkdocstrings: From 359bfdabfb2377e6f5a152d99f5212d1023422c2 Mon Sep 17 00:00:00 2001 From: Anuraag Agrawal Date: Fri, 15 Aug 2025 14:26:06 +0900 Subject: [PATCH 3/3] clean up exceptions.md --- docs/exceptions.md | 28 ---------------------------- 1 file changed, 28 deletions(-) diff --git a/docs/exceptions.md b/docs/exceptions.md index 151c6e46f1..a484dc1ef4 100644 --- a/docs/exceptions.md +++ b/docs/exceptions.md @@ -40,85 +40,57 @@ For an overview of how to work with HTTPX exceptions, see [Exceptions (Quickstar ## Exception classes ::: httpx.HTTPError - :docstring: ::: httpx.RequestError - :docstring: ::: httpx.TransportError - :docstring: ::: httpx.TimeoutException - :docstring: ::: httpx.ConnectTimeout - :docstring: ::: httpx.ReadTimeout - :docstring: ::: httpx.WriteTimeout - :docstring: ::: httpx.PoolTimeout - :docstring: ::: httpx.NetworkError - :docstring: ::: httpx.ConnectError - :docstring: ::: httpx.ReadError - :docstring: ::: httpx.WriteError - :docstring: ::: httpx.CloseError - :docstring: ::: httpx.ProtocolError - :docstring: ::: httpx.LocalProtocolError - :docstring: ::: httpx.RemoteProtocolError - :docstring: ::: httpx.ProxyError - :docstring: ::: httpx.UnsupportedProtocol - :docstring: ::: httpx.DecodingError - :docstring: ::: httpx.TooManyRedirects - :docstring: ::: httpx.HTTPStatusError - :docstring: ::: httpx.InvalidURL - :docstring: ::: httpx.CookieConflict - :docstring: ::: httpx.StreamError - :docstring: ::: httpx.StreamConsumed - :docstring: ::: httpx.StreamClosed - :docstring: ::: httpx.ResponseNotRead - :docstring: ::: httpx.RequestNotRead - :docstring: