Build Sites with Python

Use this workflow when Python 3.11 or newer is installed on the build machine. No third-party Python packages are required.

Build the bundled documentation#

From the Simple Docs repository, run:

python3 build.py

This uses the bundled manual/ directory and writes:

dist/
artifacts/manual-site.tar.gz

Build external documentation#

The external source can be in another public or private Git repository:

python3 /path/to/simple-docs/build.py \
  --source /path/to/private-project/docs \
  --output /path/to/private-project-build/site \
  --archive /path/to/private-project-build/manual-site.tar.gz

The --source value points directly to the directory containing ordered section directories and the optional images/ directory.

The generator uses core assets and selectable themes shipped beside build.py. The external repository only needs to contain documentation source.

Select a theme#

Use the light paper theme instead of the default ef-maris-dark theme:

python3 /path/to/simple-docs/build.py \
  --source /path/to/private-project/docs \
  --output /path/to/private-project-build/site \
  --archive /path/to/private-project-build/manual-site.tar.gz \
  --theme paper

See create and select themes to add a theme.

Use relative command paths#

Explicit relative paths are resolved from the current working directory:

python3 /path/to/simple-docs/build.py \
  --source ../private-project/docs \
  --output ../private-project-build/site \
  --archive ../private-project-build/manual-site.tar.gz

Absolute paths are clearer for automated jobs and avoid depending on the current working directory.

Build for a URL prefix#

The default build expects the site at the domain root. Add --base-path when a static host publishes it below a project path:

python3 /path/to/simple-docs/build.py \
  --source /path/to/private-project/docs \
  --output /path/to/private-project-build/site \
  --archive /path/to/private-project-build/manual-site.tar.gz \
  --base-path /project-name/

The generated site must be mounted at the same /project-name/ path. Rebuild when the deployment prefix changes.

Build an offline ZIP#

Add an offline archive path when readers need to open the documentation without a web server:

python3 /path/to/simple-docs/build.py \
  --source /path/to/private-project/docs \
  --output /path/to/private-project-build/site \
  --archive /path/to/private-project-build/manual-site.tar.gz \
  --offline-archive /path/to/private-project-build/manual-site-offline.zip

Extract the ZIP and open manual-site-offline/index.html. The offline pages use relative file links and embedded search data. External links work when internet access is available, but external images are rejected because they would make the documentation depend on the network.

Rebuild after changes#

Run the same command after changing Markdown. Ownership markers let the generator safely replace its previous site and archives.

An existing non-empty output directory or archive without a valid marker is left untouched. Choose a new empty output location instead of deleting an unrelated file.

The generator prepares the complete site and archives in temporary locations before replacing output. If publication fails, it attempts to restore the previous site, archives, and ownership markers. If restoration also fails, the error lists retained backup locations for manual recovery. Do not delete those backups until you have recovered the required files.

Markers must be regular files, not symlinks. Allow enough disk space for both old and new outputs while rebuilding. Publication is not a crash-safe transaction, and readers may briefly see missing paths during replacement. Do not run concurrent builds against the same output paths.

Return to the generating sites overview, compare the container workflow, use the Make helpers, or continue with serving generated sites. You can also create or select a theme.