Skip to content

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:

[format.version]
major = 0
minor = 1

[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.format.version]
major = 0
minor = 1

[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:

[format.version]
major = 0
minor = 1

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

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.