Use Make Helpers

The Makefile provides short commands for common local workflows. Direct Python and Podman commands remain available when troubleshooting or integrating with other tools.

Show available commands#

make help

Run Make from the Simple Docs repository. External documentation can remain in another public or private repository.

Podman Make helpers require GNU realpath with -m support. Make helpers also require SOURCE and BUILD_DIR paths without whitespace. Use the direct Python or Podman commands when a path contains spaces.

Generate the bundled example#

make bundle

This generates:

.build-simple-docs/
├── site/
└── manual-site.tar.gz

Generate an offline ZIP beside those hosted outputs:

make offline-bundle

The additional file is:

.build-simple-docs/manual-site-offline.zip

Extract it and open manual-site-offline/index.html. No server is required.

Preview the example with Python:

make preview PORT=8000

Open http://localhost:8000/manual/ and stop the server with Ctrl-C.

Run the example through nginx:

make example PORT=8080

Select the light paper theme for any build or runtime helper:

make bundle THEME=paper
make offline-bundle THEME=paper
make example THEME=paper PORT=8080

Generate external documentation with Python#

Override SOURCE with the documentation source directory:

make bundle SOURCE=/absolute/path/to/private-project/docs

The output remains under .build-simple-docs/ in the Simple Docs repository. Override BUILD_DIR to place generated files elsewhere:

make bundle \
  SOURCE=/absolute/path/to/private-project/docs \
  BUILD_DIR=/absolute/path/to/private-project-build

Generate external documentation in a container#

make bundle-container \
  SOURCE=/absolute/path/to/private-project/docs

This builds the reusable builder image, mounts SOURCE read-only, and writes the generated site and bundle under .build-simple-docs/.

Generate and serve the same source through nginx:

make run-container \
  SOURCE=/absolute/path/to/private-project/docs \
  PORT=8080

nginx runs in the foreground. Stop it with Ctrl-C.

Build for a project URL#

Bundle targets accept BASE_PATH:

make bundle-container \
  SOURCE=/absolute/path/to/private-project/docs \
  BASE_PATH=/project-name/

make preview and make run-container require BASE_PATH=/ because their local servers mount the generated site at the domain root.

Override helper settings#

The commonly used variables are:

SOURCE          Documentation source directory
BUILD_DIR       Generated site and bundle parent
BASE_PATH       Deployment URL prefix
THEME           Bundled theme name
PORT            Local server port
PYTHON          Python executable
PODMAN          Podman executable
REALPATH         GNU realpath executable
CHROMIUM        Chromium executable
BUILDER_IMAGE   Builder image name
RUNTIME_IMAGE   nginx runtime image name

Run project checks#

make test
make verify
make test-browser

make verify runs the unit tests and generates the hosted bundle. Use make offline-bundle when the downloadable ZIP is also needed. The optional make test-browser target builds temporary hosted and offline fixtures, then uses Chromium to exercise interactive search behavior.

Return to the generating sites overview, or review the direct Python, container, and serving workflows. See create and select themes to add a theme.