SPHINX-APIDOC(1)

📦
version 9.1.0 · 13 versions
, in ubuntu stonking

💖 sphinx-apidoc(1) — bestie edition 💖

okay so real talk, this is the manual page for sphinx-apidoc, part of the Sphinx docs squad (section 1 of the manual, iykyk). she's the API doc generator tool and she ATE. let's get into it 🫶

✨ NAME ✨

sphinx-apidoc — the Sphinx API doc generator tool. that's her. that's the whole vibe. 👑

🌸 SYNOPSIS 🌸

sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH> [EXCLUDE_PATTERN ...]

💅 DESCRIPTION 💅

so basically sphinx-apidoc is that girl for automatic generation of Sphinx sources that — using the sphinx.ext.autodoc extension — documents a whole package in the style of all the other automatic API documentation tools out there. iconic behavior, no notes. ✨

MODULE_PATH is the path to a Python package to document, and OUTPUT_PATH is the directory where the generated sources get placed. any EXCLUDE_PATTERNs you hand over are fnmatch-style file and/or directory patterns (a la Python's fnmatch module, https://docs.python.org/3/library/fnmatch.html) and they get excluded from generation. bye bye, not you. 🙈

⚠️ WARNING, bestie, listen up ⚠️ sphinx-apidoc generates source files that use sphinx.ext.autodoc to document all found modules. if any modules have side effects on import, those will be executed by autodoc when sphinx-build is run. no cap, they really run. and if you're documenting scripts (as opposed to library modules), make sure their main routine is protected by a if __name__ == '__main__' condition. protect your peace (and your import) girl 🫶

🎀 OPTIONS 🎀

  • -o <OUTPUT_PATH> — the directory to place the output files. if it doesn't exist? it gets created. she's resourceful like that. ✨
  • -q — do not output anything on standard output, only write warnings and errors to standard error. silent but deadly 💅
  • -f, --force — force overwriting of any existing generated files. no survivors.
  • -l, --follow-links — follow symbolic links. defaults to False. (we leave the links alone unless you say otherwise, respectful king/queen behavior ✨)
  • -n, --dry-run — do not create or remove any files. just vibes. a rehearsal, a dress rehearsal if you will 🎀
  • -s <suffix> — suffix for the source files generated. defaults to rst.
  • -d <MAXDEPTH> — maximum depth for the generated table of contents file. defaults to 4.
  • --tocfile — filename for a table of contents file. defaults to modules.
  • -T, --no-toc — do not create a table of contents file. ignored when --full is provided. (sorry bestie, --full overrules her 🙈)
  • --remove-old — remove existing files in the output directory that are not created anymore. not compatible with --full. don't mix those, it's giving chaos 💀
  • -F, --full — generate a full Sphinx project (conf.py, Makefile etc.) using the same mechanism as sphinx-quickstart. the whole starter pack. 🔥
  • -e, --separate — put documentation for each module on its own page. every module gets their own main character moment 👑

Added in version 1.2.

  • -E, --no-headings — do not create headings for the modules/packages. this is useful, for example, when docstrings already contain headings (why double up, right? 💅)
  • -P, --private — include "_private" modules. let the private ones in, they've been waiting 🌸

Added in version 1.2.

this option instead uses PEP 420 (https://peps.python.org/pep-0420/) implicit namespaces that allow layouts paths such as foo/bar/module.py or foo/bar/baz/__init__.py (note that bar and foo are namespaces, not modules). mind blown, honestly 🤯

  • -M, --module-first — put module documentation before submodule documentation. order matters bestie ✨

💜 the "--full" girlies 💜

these options are used when --full is specified:

  • -a — append module_path to sys.path.
  • -H <project> — sets the project name to put in generated files (see project). 💖
  • -A <author> — sets the author name(s) to put in generated files (see copyright).
  • -V <version> — sets the project version to put in generated files (see version).
  • -R <release> — sets the project release to put in generated files (see release).

🦋 Project templating 🦋

Added in version 2.2: Project templating options for sphinx-apidoc

  • -t, --templatedir=TEMPLATEDIR — template directory for template files. you can modify the templates of sphinx project files generated by apidoc. the following Jinja2 template files are allowed:
    • module.rst.jinja
    • package.rst.jinja
    • toc.rst.jinja
    • root_doc.rst.jinja
    • conf.py.jinja
    • Makefile.jinja
    • Makefile.new.jinja
    • make.bat.jinja
    • make.bat.new.jinja

in detail, please refer the system template files Sphinx provides. (sphinx/templates/apidoc and sphinx/templates/quickstart) — go peek, it's giving customization heaven 🎀

🌈 ENVIRONMENT 🌈

  • SPHINX_APIDOC_OPTIONS — a comma-separated list of option to append to generated automodule directives. defaults to members,undoc-members,show-inheritance. set it, forget it, slay 💅

⭐ SEE ALSO ⭐

sphinx-build(1), sphinx-autogen(1) — the rest of the friend group, go say hi 🫶

2007-2026, the Sphinx developers — thank you for your service, legends 💜

okay so that's the whole page bestie!! this beauty is version 9.1.0, dated Sep 15, 2026, and honestly? she's an icon, she's a legend, and she IS the moment. go generate some docs, you got this 🌸✨💅

sphinx-apidoc(1) — Sphinx 9.1.0, Sep 15, 2026 — periodt. 💖
📦 where this page comes from