feat: prettify docs (#183)

Author: mathislucka

docs/reference.md

@@ -1,3 +1,129 @@
 # API Reference
 
-::: deepset_mcp.api
+## Main Client
+::: deepset_mcp.api.client
+    options:
+        show_submodules: false
+        heading_level: 3
+        filters: [ "!^_(?!_init__)" ]
+
+## Resources
+::: deepset_mcp.api.pipeline
+    options:
+        show_submodules: false
+        heading_level: 3
+        filters: [ "!^_(?!_init__)" ]
+
+::: deepset_mcp.api.indexes
+    options:
+        show_submodules: false
+        heading_level: 3
+        filters: [ "!^_(?!_init__)" ]
+
+::: deepset_mcp.api.pipeline_template
+    options:
+        show_submodules: false
+        heading_level: 3
+        filters: [ "!^_(?!_init__)" ]
+
+::: deepset_mcp.api.haystack_service
+    options:
+        show_submodules: false
+        heading_level: 3
+        filters: [ "!^_(?!_init__)" ]
+
+::: deepset_mcp.api.integrations
+    options:
+        show_submodules: false
+        heading_level: 3
+        filters: [ "!^_(?!_init__)" ]
+
+::: deepset_mcp.api.custom_components
+    options:
+        show_submodules: false
+        heading_level: 3
+        filters: [ "!^_(?!_init__)" ]
+
+::: deepset_mcp.api.secrets
+    options:
+        show_submodules: false
+        heading_level: 3
+        filters: [ "!^_(?!_init__)" ]
+
+::: deepset_mcp.api.workspace
+    options:
+        show_submodules: false
+        heading_level: 3
+        filters: [ "!^_(?!_init__)" ]
+
+::: deepset_mcp.api.user
+    options:
+        show_submodules: false
+        heading_level: 3
+        filters: [ "!^_(?!_init__)" ]
+
+## Models
+
+::: deepset_mcp.api.shared_models
+    options:
+        show_submodules: false
+        heading_level: 3
+        filters: [ "!^_(?!_init__)" ]
+
+::: deepset_mcp.api.pipeline.models
+    options:
+        show_submodules: false
+        heading_level: 3
+        filters: [ "!^_(?!_init__)" ]
+
+::: deepset_mcp.api.indexes.models
+    options:
+        show_submodules: false
+        heading_level: 3
+        filters: [ "!^_(?!_init__)" ]
+
+::: deepset_mcp.api.pipeline_template.models
+    options:
+        show_submodules: false
+        heading_level: 3
+        filters: [ "!^_(?!_init__)" ]
+
+::: deepset_mcp.api.integrations.models
+    options:
+        show_submodules: false
+        heading_level: 3
+        filters: [ "!^_(?!_init__)" ]
+
+::: deepset_mcp.api.custom_components.models
+    options:
+        show_submodules: false
+        heading_level: 3
+        filters: [ "!^_(?!_init__)" ]
+
+::: deepset_mcp.api.secrets.models
+    options:
+        show_submodules: false
+        heading_level: 3
+        filters: [ "!^_(?!_init__)" ]
+
+::: deepset_mcp.api.workspace.models
+    options:
+        show_submodules: false
+        heading_level: 3
+        filters: [ "!^_(?!_init__)" ]
+
+## Exceptions
+
+::: deepset_mcp.api.exceptions
+    options:
+        show_submodules: false
+        heading_level: 3
+        filters: [ "!^_(?!_init__)" ]
+
+## Transport
+
+::: deepset_mcp.api.transport
+    options:
+        show_submodules: false
+        heading_level: 3
+        filters: [ "!^_(?!_init__)" ]

mkdocs.yml

@@ -6,6 +6,16 @@ theme:
     - navigation.expand
     - search.suggest
 
+markdown_extensions:
+  - toc:
+      toc_depth: 3
+  - pymdownx.highlight: # syntax highlighting (Pygments)
+      anchor_linenums: true   # optional
+      linenums: false         # set true if you want line numbers
+  - pymdownx.inlinehilite     # `#!python` etc. for inline code
+  - pymdownx.superfences      # needed so fenced/converted blocks render reliably
+  - admonition                # (optional, but commonly used)
+
 plugins:
   - search
   - mkdocstrings:
@@ -14,6 +24,23 @@ plugins:
           options:
             docstring_style: sphinx  # or numpy/sphinx
             show_source: false
+            show_signature_annotations: true
+            show_root_heading: false
+            show_root_full_path: false        # Don't show full module paths
+            show_root_members_full_path: false # Don't show full paths for members
+            show_root_toc_entry: false
+            separate_signature: true  # ← Separates signature from docstring
+            signature_crossrefs: true
+            heading_level: 2
+
+            crossrefs:
+              enable_args: true
+              enable_return: true
+
+            # Make sure all your classes are documented
+            filters: [ "!^_" ]  # Show all non-private members
+            members_order: source
+            # show_submodules: true
 
 nav:
   - Home: index.md

src/deepset_mcp/api/__init__.py

@@ -2,3 +2,6 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+from .client import AsyncDeepsetClient
+
+__all__ = ["AsyncDeepsetClient"]