mcpField
D
documenting-python-libraries

documenting-python-libraries

github.com/wdm0006开发109130 次安装2 天前更新
代码仓库

关于 documenting-python-libraries

面向编写 Python 库文档的开发者，介绍文档字符串规范与文档工具配置。内容包括 Google 风格文档字符串、Sphinx 设置、README 结构和 ReadTheDocs 构建配置。

主要功能

  1. 01Google 风格文档字符串
  2. 02快速设置 Sphinx
  3. 03在 pyproject.toml 中配置文档依赖
  4. 04README 结构指导
  5. 05ReadTheDocs 配置

适用场景

  1. 01为 Python 包编写 API 文档字符串
  2. 02设置 Sphinx 文档
  3. 03准备库的 README
  4. 04配置 ReadTheDocs 构建

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/wdm0006/python-skills --skill documenting-python-libraries

安装后在 Claude Code 中输入/documenting-python-libraries确认已加载。

附带文件SPHINX_CONFIG.mdTUTORIALS.md

详细介绍

Python 库文档

文档字符串风格（Google）

def encode(latitude: float, longitude: float, *, precision: int = 12) -> str:
    """Encode geographic coordinates to a quadtree string.

    Args:
        latitude: The latitude in degrees (-90 to 90).
        longitude: The longitude in degrees (-180 to 180).
        precision: Number of characters in output. Defaults to 12.

    Returns:
        A string representing the encoded location.

    Raises:
        ValidationError: If coordinates are out of valid range.

    Example:
        >>> encode(37.7749, -122.4194)
        '9q8yy9h7wr3z'
    """

Sphinx 快速设置

# Install
uv add --dev sphinx furo myst-parser sphinx-copybutton

# Initialize
sphinx-quickstart docs/

conf.py 核心内容：

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',  # Google docstrings
    'myst_parser',          # Markdown support
]
html_theme = 'furo'

pyproject.toml 依赖项

[project.optional-dependencies]
docs = [
    "sphinx>=7.0",
    "furo>=2024.0",
    "myst-parser>=2.0",
]

README 模板

# Package Name

[![PyPI](https://badge.fury.io/py/package.svg)](https://pypi.org/project/package/)

Short description of what it does.

## Installation

uv add package

## Quick Start

from package import function
result = function(args)

## Documentation

Full docs at [package.readthedocs.io](https://package.readthedocs.io/)

ReadTheDocs（.readthedocs.yaml）

version: 2
build:
  os: ubuntu-22.04
  tools:
    python: "3.11"
sphinx:
  configuration: docs/conf.py
python:
  install:
    - method: pip
      path: .
      extra_requirements: [docs]

详细设置请参阅：

检查清单

README:
- [ ] Clear project description
- [ ] Installation instructions
- [ ] Quick start example
- [ ] Link to full documentation

API Docs:
- [ ] All public functions documented
- [ ] Args, Returns, Raises sections
- [ ] Examples in docstrings
- [ ] Type hints included

了解更多

本技能基于 Will McGinnis 撰写的《高质量 Python 库开发指南》中的“文档”部分。以下文章提供了更深入的介绍：

评论

支持 Markdown