SPHINX-AUTOBUILD(1)

📦
version 2025.08.25 · 3 versions
, in fedora 43

💖 SPHINX-AUTOBUILD 💖

okay bestie so this is sphinx-autobuild, a lil tool from the User Commands corner of your system, and honestly? it's giving "your docs rebuild themselves while you vibe". you point it at a Sphinx docs folder, it watches for changes, and boom 💥 — fresh build, live server, no manual re-running. no cap.

🌸 NAME 🌸

sphinx-autobuild — autobuild a Sphinx directory when a change is detected 🦋

like literally that's it. change a file, it notices, it rebuilds. the way that it just watches you edit is lowkey iconic.

✨ DESCRIPTION ✨

here's how you summon it:

usage: sphinx-autobuild [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]

slay. now let's break it down piece by piece 💅

🎀 positional arguments

  • SOURCE_DIR — the path to your documentation source files. this is where your docs actually live, bestie 🏠
  • OUTPUT_DIR — the path to your output directory. this is where the built stuff gets dumped ✨
  • filenames — (optional) a specific list of files you wanna rebuild. ⚠️ heads up: this gets ignored if you pass --write-all. so don't be out here specifying filenames and --write-all at the same time expecting filenames to matter, because they will NOT 🙈

👑 options

  • -h, --help — shows this help message and dips out. the classic.
  • --version — shows the program's version number and exits. go off, version info 💫

🧚 general options

  • --builder, -b BUILDER — which builder to use. default is 'html' 💖
  • --jobs, -j N — run in parallel with N processes, when possible. and if you pass 'auto'? it just uses the number of CPU cores. multitasking queen 🔥
  • --write-all, -a — write all files. by default it only writes new and changed files, so this is the "do the whole thing" button 💅
  • --fresh-env, -E — don't use a saved environment, always read all files. no recycling, we're starting fresh 🧼✨

🌈 path options

  • --doctree-dir, -d PATH — directory for doctree and environment files. default: OUTPUT_DIR/.doctrees 📁
  • --conf-dir, -c PATH — directory for the configuration file (conf.py). default: SOURCE_DIR 🗂️

🫶 build configuration options

  • --isolated, -C — use no configuration file at all, only use settings from -D options. solo mode, main character energy ✨
  • --define, -D setting=value — override a setting in the configuration file. speak it into existence 💫
  • --html-define, -A name=value — pass a value into HTML templates 🎀
  • --tag, -t TAG — define tag: include "only" blocks with TAG 🏷️
  • --nitpicky, -n — nitpicky mode: warn about all missing references. it's in its detail-oriented era and honestly? respect 💅

💬 console output options

  • --verbose, -v — increase verbosity. can be repeated, so stack it like it's a combo 🗣️
  • --quiet, -q — no output on stdout, just warnings on stderr. minimal, mysterious 🤫
  • --silent, -Q — no output at all. not even warnings. total silence, the void, nothing 😶
  • --color — do emit colored output. default: auto-detect 🌈
  • --no-color, -N — do not emit colored output. default: auto-detect 🚫🌈

⚠️ warning control options

bestie this whole section is about warnings, errors, and how dramatic you want the tool to be about them. choose your fighter.
  • --warning-file, -w FILE — write warnings (and errors) to the given file 📝
  • --fail-on-warning, -W — turn warnings into errors. harsh but fair 💀
  • --show-traceback, -T — show full traceback on exception 🔍
  • --pdb, -P — run Pdb on exception. debugging era 🐛
  • --exception-on-warning — raise an exception on warnings. no warnings allowed, periodt 🚫

🌸 autobuild options

  • --port PORT — port to serve documentation on. 0 means find and use a free port 🚪
  • --host HOST — hostname to serve documentation on 🏡
  • --re-ignore RE_IGNORE — regular expression for files to ignore, when watching for changes 🙈
  • --ignore IGNORE — glob expression for files to ignore, when watching for changes 🌀
  • --no-initial — skip the initial build. no warm-up, straight to business 😤
  • --open-browser — open the browser after building documentation 🌐
  • --delay DELAY — how long to wait before opening the browser ⏳
  • --watch DIR — additional directories to watch 👀
  • --pre-build COMMAND — additional command(s) to run prior to building the documentation 🏃♀️
  • --post-build COMMAND — additional command(s) to run after building the documentation 🎬

aaaand that's the whole thing, bestie 🎀 go forth and let your docs rebuild themselves. you're welcome 💖

mwah 💋 this page is from sphinx-autobuild 2025.08.25, dated September 2025 — catch you in the next rebuild, love u, bye 🦋✨

📦 where this page comes from