Migrate API docs to mkdocstrings

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`

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;
+}

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:

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: ""
+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

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