{"id":2292,"library":"sphinx-argparse","title":"Sphinx Argparse Extension","description":"sphinx-argparse is a Sphinx extension that automatically documents `argparse` commands and options by parsing Python scripts or functions. It helps generate command-line interface documentation directly from your `argparse` definitions. The current version is 0.5.2, and it maintains a moderate release cadence, with several updates per year.","status":"active","version":"0.5.2","language":"en","source_language":"en","source_url":"https://github.com/sphinx-doc/sphinx-argparse/","tags":["sphinx","documentation","argparse","extension","cli"],"install":[{"cmd":"pip install sphinx-argparse","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"This is a Sphinx extension and requires Sphinx to run.","package":"sphinx","optional":false}],"imports":[{"note":"sphinx-argparse is enabled as a Sphinx extension in conf.py, not imported directly into Python code.","symbol":"sphinx_argparse","correct":"# In conf.py\nextensions = [\n    'sphinx_argparse'\n]"}],"quickstart":{"code":"# conf.py\nimport os\nimport sys\nsys.path.insert(0, os.path.abspath('.'))\n\nproject = 'My Project'\ncopyright = '2023, Your Name'\nextensions = [\n    'sphinx_argparse'\n]\n\n# my_script.py (example script to document)\nimport argparse\n\ndef main():\n    parser = argparse.ArgumentParser(description='A sample command line tool.')\n    parser.add_argument('--foo', help='The foo argument.', default='bar')\n    parser.add_argument('-v', '--version', action='version', version='%(prog)s 1.0')\n    subparsers = parser.add_subparsers(dest='command', help='sub-command help')\n    \n    parser_a = subparsers.add_parser('subcommand-a', help='subcommand a help')\n    parser_a.add_argument('--baz', help='The baz argument for subcommand a.')\n\n    args = parser.parse_args()\n    print(f'Args: {args}')\n\nif __name__ == '__main__':\n    main()\n\n# my_documentation_page.rst\n# .. argparse:: my_script.py\n#    :func: main.parser\n#    :prog: my-cli\n#\n# (Note: For this example, you would place `my_script.py` in the same directory as `conf.py` or adjust `sys.path` accordingly.)","lang":"python","description":"To use `sphinx-argparse`, first add `'sphinx_argparse'` to your `extensions` list in `conf.py`. Then, create a Python script with an `argparse.ArgumentParser` definition. Finally, use the `.. argparse::` directive in your reStructuredText or MyST documentation files, pointing to the script or a function that returns the parser. You can specify the `prog` name and other options."},"warnings":[{"fix":"Ensure your project's Python environment is 3.10 or newer when using sphinx-argparse v0.5.0+.","message":"Starting with version 0.5.0, `sphinx-argparse` officially requires Python 3.10 or newer. Older versions supported Python 3.7+.","severity":"breaking","affected_versions":">=0.5.0"},{"fix":"Update any hardcoded repository URLs or source links to `https://github.com/sphinx-doc/sphinx-argparse/`.","message":"The project's GitHub repository moved from `ashb/sphinx-argparse` to `sphinx-doc/sphinx-argparse`. Older links or internal references might point to the outdated repository.","severity":"gotcha","affected_versions":"<0.5.0 (for old source links)"},{"fix":"Verify that the path and function specified in the `.. argparse::` directive are correct and accessible by Sphinx during the build process. Debug import errors by temporarily adding print statements to your `conf.py`.","message":"When documenting a function that returns an `ArgumentParser` instance, ensure the `func` option in the `argparse` directive correctly points to the function (e.g., `my_module.my_function`). If documenting a script, ensure the script is importable and that `sys.path` is configured correctly in `conf.py`.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}