Registry / serialization / haystack-pydoc-tools

haystack-pydoc-tools

library0.7.0pypypiunverified

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.

serialization

pip install haystack-pydoc-tools

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · HAYSTACK-PYDOC-TOO

haystack-pydoc-tools

serializationpythonv0.7.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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.")

Debug

Known issues

breakingThe `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.

affects: All versions of haystack-pydoc-tools using pydoc-markdown (up to 0.7.0), when used with setuptools>=82.0.0

deprecatedThe 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.

affects: All versions of haystack-pydoc-tools using pydoc-markdown (up to 0.7.0)

Errors

Common errors & fixes

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.

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'

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.

Upgrade

Version history

0.7.0latest on PyPI · released Feb 18, 2026

Audit

Dependencies

pydoc-markdownrequiredCore dependency for Markdown-based documentation generation. Currently problematic and slated for replacement.

setuptoolsrequiredIndirectly required by pydoc-markdown, specific versions cause breakage.

griffeoptionalPlanned replacement for pydoc-markdown, will become a future core dependency.

mkdocstringsoptionalOften used in conjunction with mkdocs for generating API docs from code.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/unknown/haystack-pydoc-tools#readme ↗

packagehttps://pypi.org/project/haystack-pydoc-tools/ ↗

docshttps://github.com/unknown/haystack-pydoc-tools#readme ↗