plesty docs#

Build, preview, and deploy the Sphinx documentation for a Plesty project.

Subcommands#

  • plesty docs serve — local preview with live reload

  • plesty docs deploy — publish to a remote pages branch

serve#

plesty docs serve [--dev-addr IP:PORT]

Starts a local web server that renders the project documentation and automatically reloads whenever a .md or .rst file changes. Useful during active documentation writing.

Options#

Option

Default

Description

--dev-addr

127.0.0.1:8000

Host and port for the preview server

Example#

# Default address
plesty docs serve

# Listen on all interfaces at a custom port
plesty docs serve --dev-addr 0.0.0.0:9000

Press Ctrl+C to stop the server.

deploy#

plesty docs deploy REMOTE_URL TARGET_BRANCH (--release | --latest)

Builds the Sphinx documentation and pushes it to TARGET_BRANCH on the repository at REMOTE_URL, suitable for GitLab Pages. The branch is created as an orphan if it does not yet exist.

--release and --latest are mutually exclusive and one is required:

Flag

Behaviour

--latest

Publishes to html/latest/ — for commits to the default branch

--release

Publishes to html/releases/<major>.<minor>/ — for tagged releases

Example#

# Deploy development snapshot (latest)
plesty docs deploy \
  https://gitlab-ci-token:${CI_BOT_TOKEN}@gitlab.com/plesty/my-device.git \
  docs-build \
  --latest

# Deploy a versioned release
plesty docs deploy \
  https://gitlab-ci-token:${CI_BOT_TOKEN}@gitlab.com/plesty/my-device.git \
  docs-build \
  --release

In practice this command is called by the deploy-docs CI component and does not need to be run manually.