pytkdocs

What it is and what it does

pytkdocs is a command-line tool that introspects Python source code and outputs structured documentation as JSON. It reads a JSON request describing which Python objects to document (modules, classes, functions, etc.), then loads those objects, parses their docstrings in Google, NumPy, or reStructuredText format, and returns a JSON response with the extracted metadata, docstring sections, source locations, and object hierarchies. It supports filtering by name patterns, selecting inherited members, and configurable docstring parsing options.

The tool is designed to be used as a subprocess by other programs—notably mkdocstrings—feeding it single lines of JSON and reading back single lines of JSON in line-by-line mode. However, the project is now deprecated in favor of Griffe, a more powerful alternative. If you are starting a new documentation pipeline, Griffe is recommended; pytkdocs remains functional for existing integrations but is no longer actively developed.

Use it for:

• Feed Python module paths to pytkdocs as JSON to extract docstrings and signatures for auto-generated API documentation.
• Integrate pytkdocs into mkdocstrings or similar documentation generators to parse Python source without importing it.
• Filter and select specific members of a module (e.g., public API only) and output structured metadata for custom doc tools.
• Parse and normalize docstrings across multiple styles (Google, NumPy, reStructuredText) into a common JSON format.
• Analyze Python code structure (classes, methods, attributes) and their documentation in a subprocess without loading the module directly.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Extracts and serializes Python object documentation (modules, classes, functions, attributes) from source code, accepting JSON input describing what to document and outputting structured JSON with parsed docstrings and metadata.

Yes, if you are maintaining an existing tool or workflow that already depends on pytkdocs. No, if you are starting a new documentation project—the maintainers explicitly recommend Griffe as a more powerful alternative. The tool is stable and has no known vulnerabilities, but its aging maintenance status (last release 523 days ago) and deprecation notice mean it should not be the first choice for new integrations.

Install

pytkdocs on PyPI

pip install pytkdocs

uv add pytkdocs

poetry add pytkdocs

Installing pytkdocs

Before you install

Low friction install with three lightweight runtime dependencies. Maintenance status is aging—last release was 523 days ago—and the project itself recommends Griffe as a more powerful alternative, so consider whether this tool still fits your documentation workflow.

License in practice

Licensed under ISC (permissive), allowing free use, modification, and distribution with minimal restrictions.

Quickstart

pip install pytkdocs

# Feed JSON on stdin describing what to document
echo '{"objects": [{"path": "mymodule", "members": true, "docstring_style": "google"}]}' | pytkdocs

Requires Python 3.9 or later; designed as a subprocess tool reading and writing JSON, not a library for direct import.

Verify before relying

• Whether the aging maintenance status (last release 523 days ago) affects compatibility with recent Python versions despite classifier claims.
• Real-world performance on large codebases or deeply nested object hierarchies.
• Whether Griffe is a drop-in replacement or requires significant workflow changes.

Package facts

Evidence: pytkdocs-0.16.5-py3-none-any.whl

Keywords: python, source, signature, docs

Tags

More Software Development packages