From 4b75eeadccb2e8e5f5b71887ca5cc0c7901a22f1 Mon Sep 17 00:00:00 2001 From: Emmett Walsh Date: Tue, 6 Jan 2026 17:18:24 +0000 Subject: [PATCH] Add docstring format documentation to CLI usage guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documents the three supported docstring formats (Google, NumPy, and RST) and their behavior differences when generating help text. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- docs/using-cli.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/docs/using-cli.md b/docs/using-cli.md index bdfcb7db..aa9000b2 100644 --- a/docs/using-cli.md +++ b/docs/using-cli.md @@ -230,3 +230,39 @@ Adding the `-v` or `--verbose` flag turns on verbose mode. This will eg reveal private members in the usage string. Often these members will not actually be usable from the command line tool. As such, verbose mode should be considered a debugging tool, but not fully supported yet. + + +## Documenting your CLI + +Python Fire automatically generates help text from your function and class +docstrings. Fire supports three common docstring formats: + +- **Google-style** docstrings +- **NumPy-style** docstrings +- **reStructuredText (Sphinx)** style docstrings + +The docstring support is **best-effort**, and notably many features of rst +docstrings are not currently handled. Additional limitations are listed at the +top of +[fire/docstrings.py](https://github.com/google/python-fire/blob/v0.3.0/fire/docstrings.py). + +### Behavior differences between formats + +When testing the different docstring styles (e.g., with +`python your_script.py your_function -- --help`), you may notice some +differences in how type information is displayed: + +- **Google-style** shows `Type:` for arguments when type annotations are + present (e.g., `Type: str`, `Type: int`). +- **NumPy-style** and **rst-style** may not show `Type:` lines in the same way + (though they still show `Default:` values and descriptions). Fire's docstring + parser for NumPy/rst is more conservative in attaching type information. + +### Common behavior across all formats + +Regardless of which docstring format you choose, Fire will: + +- Use the first-line summary as the command's NAME/DESCRIPTION in the help text +- Populate POSITIONAL ARGUMENTS and FLAGS from parameter descriptions +- Automatically convert optional arguments to flags (e.g., `--arg` or `-a` for + short flags)