Haystack Pydoc Tools

0.7.0 · active · verified Thu Apr 16

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.

Common errors

```
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.
```
cause The `pydoc-markdown` dependency internally uses `pkg_resources`, which has been deprecated and removed in recent `setuptools` versions (e.g., 82.0.0+).

fix To resolve the immediate issue and allow installation, pin your `setuptools` version to an older release: `pip install 'setuptools<82.0.0'`.
```
ModuleNotFoundError: No module named 'pkg_resources'
```
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.

fix Downgrade your `setuptools` package: `pip install 'setuptools<82.0.0'`. This will restore the `pkg_resources` module needed by the `pydoc-markdown` dependency.

Warnings

breaking 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.
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.
deprecated 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.
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.

Install

pip install haystack-pydoc-tools Install stable version

Quickstart

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.

# This library is primarily used internally by the Haystack project for documentation generation.
# Its usage is typically through configuration in an mkdocs.yml file and Markdown directives,
# rather than direct Python imports for application development.

# Example of a generic mkdocs.yml setup using mkdocstrings (which haystack-pydoc-tools integrates with):
# mkdocs.yml
# site_name: My Project Docs
# theme: material
# plugins:
#   - search
#   - mkdocstrings: 
#       handlers:
#         python:
#           paths:
#             - src
#
# Example of a Markdown file (e.g., docs/api.md) using mkdocstrings directive:
# # My API Documentation
#
# ::: my_module.MyClass

print("Haystack-pydoc-tools facilitates documentation builds. Its direct Python API for end-users is not a primary interaction point.")

view raw JSON →