publync - publish documentation by syncing it

[Home | GitLab | crates.io | ReadTheDocs]

Overview

The publync tool builds a project's documentation (e.g. using a Tox "docs" environment to run mkdocs) and then copies the generated files over to their final destination (e.g. using the rsync tool to copy the files to a web server).

Sample configuration

publync.toml

The publync tool will first look for a publync.toml file in the specified project directory (the current directory by default). The simplest type of configuration is to tell publync to use Tox and to use rsync with a specified remote directory:

mediaType = "vnd.ringlet.misc.publync.config/publync.v0.1+toml"

[build.tox]

[sync.rsync]
remote = "username@hostname:path"

pyproject.toml

If there is no publync.toml file in the project directory, the publync tool will then look for a [tool.publync] section in the pyproject.toml file. The same configuration as above would be represented as:

[tool.publync]
mediaType = "vnd.ringlet.misc.publync.config/publync.v0.1+toml"

[tool.publync.build.tox]

[tool.publync.sync.rsync]
remote = "username@hostname:path"

Building the documentation

For the moment, the only supported method is invoking the Python Tox test runner.

Tox

The tox section of the publync configuration file may define the following settings:

• environment (default: "docs"): the Tox environment to invoke
• output-path (default: "site/docs"): the path where the documentation will be generated by the Tox invocation
• program (default: "tox"): the Tox program to invoke

The program setting may be overridden (also in the user's publync overrides file) e.g. to point to a virtual environment where tox-uv is also installed.

Syncing the documentation

For the moment, the only supported method is invoking the rsync tool.

rsync

The tox section of the publync configuration file may define the following settings:

• remote (mandatory): the destination for the rsync operation. This string may be in any form that the rsync tool accepts, e.g. a bare pathname, "hostname:path", "username@hostname:path", etc. Note that publync will always append a slash character (/) at the end if there is none.

The overrides file

After parsing the publync.toml file in the project directory, publync will also look for a file in the current user account's home directory that may override some of the settings, e.g. specifying a different Tox program to use. Currently publync only processes a single overrides file, .config/publync/overrides.d/overrides.toml, but in the future more files in the same directory and in other system-wide directories may be processed.

A sample overrides.toml file that specifies the Tox program to use would look like this:

mediaType = "vnd.ringlet.misc.publync.config/publync.v0.1+toml"

[build.tox]
program = "/home/jrl/lang/python/devel/venv-tox-uv/bin/tox"

Examples

Show the configuration that publync has found in the publync.toml or pyproject.toml files in the current directory after applying any overrides found in the user's publync overrides file:

publync show config

Show the configuration that publync has found in the publync.toml or pyproject.toml files in a different directory. This time, do not apply any overrides; only show the configuration as defined in the project files:

publync -p ../../text/fnmatch-regex show config --no-overrides

Build the documentation, e.g. invoke Tox to do that, displaying more diagnostic messages:

publync -v build

Show what commands would be executed to sync the already-built documentation:

publync --noop sync

Read configuration files found in a different directory, then build the documentation located there as specified by the read configuration, and sync it to its remote location:

publync --project-dir ../../text/fnmatch-regex run

Contact

The publync library was written by Peter Pentchev. It is developed in a GitLab repository. This documentation is hosted at Ringlet with a copy at ReadTheDocs.