如何在pdoc中隐藏特定类的继承文档

在Python项目文档生成工具pdoc中，当基于Pydantic模型生成类文档时，开发者可能会遇到需要隐藏继承成员或特定方法的情况。本文将通过一个典型场景，详细介绍如何通过自定义模板实现这一需求。

问题背景

当使用pdoc为继承自Pydantic的BaseModel类生成文档时，默认会显示以下内容：

1. 从BaseModel继承的模型方法（如model_dump、model_validate等）
2. 显式的"继承成员"章节

这些自动生成的内容可能会干扰开发者想要展示的核心文档结构。

解决方案

方法一：自定义模板覆盖

pdoc支持通过创建自定义模板来修改文档生成行为。具体步骤如下：

1. 创建模板扩展文件（如template.html）
2. 在模板中重写相关宏定义
3. 使用--template参数指定自定义模板

对于隐藏继承成员章节，可以重写inherited宏：

{% macro inherited() %}
{% if not obj.__module__.startswith('your_module') %}
    {{ super() }}
{% endif %}
{% endmacro %}

方法二：控制成员可见性

要隐藏特定的模型方法，可以重写is_public宏：

{% macro is_public(d) %}
{% if not d.name.startswith('model_') %}
    {{ super() }}
{% endif %}
{% endmacro %}

实现原理

pdoc的模板系统基于Jinja2，通过覆盖默认模板中的宏定义，开发者可以：

• 过滤特定名称的成员
• 根据模块路径控制文档生成
• 完全自定义文档结构

注意事项

1. 模板覆盖会影响所有文档生成，建议结合条件判断使用
2. 隐藏继承方法可能会影响API文档的完整性
3. 复杂的过滤逻辑可能会增加维护成本

最佳实践

对于大型项目，建议：

1. 建立统一的文档规范
2. 将模板自定义逻辑封装为项目基础设施
3. 在CI流程中加入文档生成检查

通过合理使用pdoc的模板系统，开发者可以生成更符合项目需求的API文档，同时保持文档工具链的自动化优势。