Publish workflow module#

python/src/dotfiles/publish.py owns docs publish configuration resolution and the GitHub Pages publish execution flow.

High-level structure#

publish.py
|-- PublishArgs request model
|-- docs path resolver
|   `-- DocsPaths via _docs_paths
|-- config resolution
|   |-- python/src/dotfiles/dotfiles-config.ini defaults
|   |-- *_OVERRIDE environment overrides
|   `-- CLI flag overrides
`-- publish execution
     |-- clean worktree + branch checks
     |-- optional docs build
     `-- _publish_docs
         |-- commit message generation
         `-- gh-pages push command plan

  • publish_with_config resolves config and applies safety checks.

  • _docs_paths computes docs/_build/html once and shares it across build/publish steps.

  • _publish_docs builds the publish command plan and executes it.

  • dotfiles.git provides shared git helpers for branch/clean checks scoped to project_dir.

  • Docs build output for publish targets docs/_build/html.

Execution order#

  1. main.publish builds a PublishArgs request from CLI flags.

  2. publish_with_config resolves precedence: flag, env, ini default from python/src/dotfiles/dotfiles-config.ini.

  3. publish_with_config verifies clean worktree and branch policy.

  4. For non-dry-run, docs are built before publish command execution.

  5. _publish_docs commits HTML output and pushes gh-pages.