playbooks

home / skills / dmitriiweb / extract-emails / google-docstring-assistant

google-docstring-assistant skill

/.codex/skills/google-docstring-assistant

This skill helps you write Python docstrings in Google style, with clear sections and examples, improving code readability and maintenance.

npx playbooks add skill dmitriiweb/extract-emails --skill google-docstring-assistant

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
1.5 KB
---
name: google-docstring-assistant
description: Write Python docstrings following the Google Python Style Guide, using clear sections and examples.
---

# Google Docstring Assistant

## Quick start
- Write docstrings using the Google Python Style Guide structure (Args, Returns, Raises, Examples, Attributes, etc.).
- Keep sections as headers followed by indented blocks; break sections by resuming unindented text.
- When types are annotated in code, omit them in docstrings unless clarity is improved.
- Use `Examples` blocks with literal blocks (`::`) for commands or code snippets.
- Document module-level variables consistently (all in `Attributes` or inline), and list TODOs in a `Todo` section.
- See `references/google_docstring_rules.md` for full guidance and examples.

## Workflow
1) **Choose sections**  
   - Functions: include `Args`, `Returns`, and `Raises` as needed.  
   - Modules/classes: use `Attributes` and `Todo` when relevant; keep formatting consistent.  

2) **Write clearly**  
   - One docstring per object; keep it concise and informative.  
   - Use indentation under each section header; separate sections by returning to unindented text.  
   - Prefer Google-style wording; avoid duplicating annotated types unless helpful.  

3) **Examples and scripts**  
   - Use `Examples:` with indented literal blocks for shell commands or code snippets.  
   - Include multi-line descriptions when needed; keep formatting readable.  

## Reference
- `references/google_docstring_rules.md`: full style description and examples.

Overview

This skill writes Python docstrings that follow the Google Python Style Guide, producing clear sections such as Args, Returns, Raises, Examples, Attributes, and Todo. It is tailored for projects that parse web content—like extracting emails and LinkedIn links from URLs—so docstrings highlight parsing behavior, edge cases, and expected outputs. The result is consistent, searchable, and ready for automated documentation tools.

How this skill works

The assistant inspects function, class, and module signatures and generates a single, concise docstring per object using Google-style headers. It omits redundant type annotations when types are present in code, includes Examples blocks with literal code or shell snippets, and documents module-level variables in an Attributes section or inline consistently. It flags TODOs in a Todo section and clarifies parsing edge cases (rate limits, timeouts, HTML variations).

When to use it

  • Adding or improving docstrings for functions that fetch and parse HTML to extract emails or LinkedIn profiles.
  • Documenting classes that manage scraping sessions, rate limiting, or persistent connections.
  • Preparing code for automated documentation generation or developer handoff.
  • Creating clear Examples for CLI tools or scripts that run URL-based extraction workflows.
  • Standardizing module-level configuration and TODOs across a parsing library.

Best practices

  • Include Args, Returns, and Raises only when relevant; keep each section short and focused.
  • Use Examples with literal blocks (::) for sample requests, expected outputs, and CLI usage.
  • Avoid repeating type annotations already present in function signatures unless it improves clarity.
  • Document common parsing failure modes (HTTP errors, missing selectors, invalid input) in Raises.
  • List module-global variables in Attributes or annotate inline consistently across the project.

Example use cases

  • Documenting extract_emails(url) to show input URL expectations, returned email list format, and network-related exceptions.
  • Describing a LinkedInLinkParser class with Attributes for selectors, session timeout, and a Todo for OAuth integration.
  • Providing Examples for a command-line scraper that reads URLs from stdin and writes found emails to JSON.
  • Annotating a utility that normalizes LinkedIn profile URLs and demonstrates edge cases in Examples.
  • Adding a module-level Todo section listing future enhancements like concurrency or headless browser support.

FAQ

Should I repeat type hints in the docstring?

No—omit types that are already present in the function signature unless repeating them makes the behavior clearer.

How do I show a CLI or shell example?

Use an Examples section with an indented literal block (::) and include the exact command and expected output.