plesty.sdk.commands.docs.deploy

The plesty docs deploy command.

Attributes

RELEASE_TAG

Functions

deploy_command(→ None)

Build and push the documentation pages for the Plesty project in the

run_git(→ int)

Run a git command in the current working directory.

version_tuple(→ tuple[int, int])

Parse a version tag into a tuple of the form (major, minor).

write_redirect(→ None)

Write an HTML stub that forwards a directory index to target.

update_versions_json(→ list[str])

Rewrite the manifest the sidebar version picker reads, plus the two

Module Contents

plesty.sdk.commands.docs.deploy.RELEASE_TAG
plesty.sdk.commands.docs.deploy.deploy_command(context: plesty.sdk.context.ApplicationContext, remote_url: str, target_branch: str, release: bool) → None

Build and push the documentation pages for the Plesty project in the current working directory to the <TARGET_BRANCH> of the repository at <REMOTE_URL>. The branch is created if it does not yet exist.

Parameters:
Return type:

None

plesty.sdk.commands.docs.deploy.run_git(args: list[str], expected_exit_codes: set[int] = {0}) → int

Run a git command in the current working directory.

Parameters:

  • args (list[str]) – The arguments and flags to be passed to the git command.

  • expected_exit_codes (set[int]) – Exit codes that should not raise an exception.

Returns:

The exit code of the git command.

Raises:

click.ClickException – If the exit code is not in expected_exit_codes.

Return type:

int

plesty.sdk.commands.docs.deploy.version_tuple(version_tag: str) → tuple[int, int]

Parse a version tag into a tuple of the form (major, minor).

Parameters:

version_tag (str) – The version tag to be parsed in ‘major.minor’ format.

Returns:

Version tuple of the form (major, minor) as integers.

Return type:

tuple[int, int]

plesty.sdk.commands.docs.deploy.write_redirect(path: str, target: str) → None

Write an HTML stub that forwards a directory index to target.

A meta refresh rather than a script: the stubs sit at the entry points a reader reaches first, and they have to work before — and without — any JavaScript.

Parameters:

  • path (str) – The file to write.

  • target (str) – The redirect target, relative to the stub’s own directory.

Return type:

None

plesty.sdk.commands.docs.deploy.update_versions_json(html_dir: str, new_version_tag: str | None) → list[str]

Rewrite the manifest the sidebar version picker reads, plus the two redirect stubs that point a bare directory URL at a real page.

Every entry’s URL is relative to html_dir, the module root — the picker resolves them against that root, which is /<slug>/ on docs.plesty.net and /<group>/<project>/ on GitLab Pages. Releases are listed newest first, below the latest development docs.

Both deploy modes call this. A release adds its own entry; a latest deploy adds none but still refreshes the manifest, which is how modules that have never been tagged get a picker at all, and how branches written by an older SDK pick up the current format.

A release whose pages cannot show the picker is published and reachable by URL, but is left out of the manifest: advertising a version the reader cannot switch back out of is worse than not offering it.

Parameters:

  • html_dir (str) – The module root, containing latest/ and releases/.

  • new_version_tag (str | None) – The release tag to add in ‘major.minor’ format, or None when deploying the latest development docs.

Returns:

The release tags left out of the manifest, in descending order.

Return type:

list[str]