{"id":9034,"library":"haystack-pydoc-tools","title":"Haystack Pydoc Tools","description":"Haystack-pydoc-tools is a utility library providing custom tools for generating API documentation for the Haystack project, primarily used within its documentation build process. It assists in creating Python API documentation in Markdown format, historically leveraging `pydoc-markdown`. The library is currently at version 0.7.0 and follows a manual, irregular release cadence tied to the Haystack project's documentation needs.","status":"active","version":"0.7.0","language":"en","source_language":"en","source_url":"https://github.com/deepset-ai/haystack-pydoc-tools","tags":["documentation","mkdocs","pydoc","haystack","deepset","developer-tool"],"install":[{"cmd":"pip install haystack-pydoc-tools","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for Markdown-based documentation generation. Currently problematic and slated for replacement.","package":"pydoc-markdown","optional":false},{"reason":"Indirectly required by pydoc-markdown, specific versions cause breakage.","package":"setuptools","optional":false},{"reason":"Planned replacement for pydoc-markdown, will become a future core dependency.","package":"griffe","optional":true},{"reason":"Often used in conjunction with mkdocs for generating API docs from code.","package":"mkdocstrings","optional":true}],"imports":[],"quickstart":{"code":"# This library is primarily used internally by the Haystack project for documentation generation.\n# Its usage is typically through configuration in an mkdocs.yml file and Markdown directives,\n# rather than direct Python imports for application development.\n\n# Example of a generic mkdocs.yml setup using mkdocstrings (which haystack-pydoc-tools integrates with):\n# mkdocs.yml\n# site_name: My Project Docs\n# theme: material\n# plugins:\n#   - search\n#   - mkdocstrings: \n#       handlers:\n#         python:\n#           paths:\n#             - src\n#\n# Example of a Markdown file (e.g., docs/api.md) using mkdocstrings directive:\n# # My API Documentation\n#\n# ::: my_module.MyClass\n\nprint(\"Haystack-pydoc-tools facilitates documentation builds. Its direct Python API for end-users is not a primary interaction point.\")","lang":"python","description":"Haystack-pydoc-tools is a documentation utility. Its typical 'quickstart' involves integrating it within an MkDocs project using `mkdocstrings` to generate API documentation from Python code, rather than direct programmatic interaction via Python imports. The example demonstrates a conceptual `mkdocs.yml` configuration and a Markdown directive, reflecting how the underlying documentation generation process works."},"warnings":[{"fix":"Pin `setuptools` to a version less than 82.0.0 in your environment (e.g., `pip install 'setuptools<82.0.0'`). The Haystack project is planning to migrate to `griffe` to resolve this.","message":"The `pydoc-markdown` dependency, currently central to `haystack-pydoc-tools`, is unmaintained and incompatible with `setuptools` versions 82.0.0 and above, which removed the `pkg_resources` module. This causes installation and build failures.","severity":"breaking","affected_versions":"All versions of haystack-pydoc-tools using pydoc-markdown (up to 0.7.0), when used with setuptools>=82.0.0"},{"fix":"Monitor the `deepset-ai/haystack-pydoc-tools` GitHub repository for updates and migration guides to `griffe`. Be prepared for potential changes in `mkdocs.yml` configurations or documentation directives once the migration is complete.","message":"The underlying `pydoc-markdown` library, on which `haystack-pydoc-tools` currently relies, is no longer actively maintained. The Haystack project intends to replace this dependency with `griffe` in a future release, which will likely involve changes to documentation configuration.","severity":"deprecated","affected_versions":"All versions of haystack-pydoc-tools using pydoc-markdown (up to 0.7.0)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"To resolve the immediate issue and allow installation, pin your `setuptools` version to an older release: `pip install 'setuptools<82.0.0'`.","cause":"The `pydoc-markdown` dependency internally uses `pkg_resources`, which has been deprecated and removed in recent `setuptools` versions (e.g., 82.0.0+).","error":"UserWarning: pkg_resources is deprecated as an API. See https://setuptools.pypa.io/en/latest/pkg_resources.html. The pkg_resources package is slated for removal as early as 2025-11-30. Refrain from using this package or pin to Setuptools<81."},{"fix":"Downgrade your `setuptools` package: `pip install 'setuptools<82.0.0'`. This will restore the `pkg_resources` module needed by the `pydoc-markdown` dependency.","cause":"This error occurs when `setuptools` version 82.0.0 or higher is installed, as it has removed the `pkg_resources` module, which `pydoc-markdown` (a dependency of `haystack-pydoc-tools`) relies on.","error":"ModuleNotFoundError: No module named 'pkg_resources'"}]}