Reference¶
This chapter provides an exhaustive list of all configuration settings, command-line options and template bindings of Soho. If you did not do so yet, you may want to have a look at the Tutorial first.
Configuration file settings¶
The configuration file (usually named sohoconf.py
) is a standard
Python module that may define the following variables:
asset_dir
The directory where assets (images, stylesheets, etc.) live. Must be set to
None
if no such directory exists.Default:
'./assets'
.assets_only
If set, process only assets, not source files. This may be useful if the only changes are on the CSS, for example.
Default:
False
.base_url
The base URL of the web site. This is used only to generate the URLs in the Sitemap. If you want the Sitemap to have valid URLs, this variable must be set.
Default:
'http://exemple.com/soho/default-base-url'
do_nothing
If set, no directories nor files are created. This can be useful to test a new configuration. Note that you can combine this setting with
force
(see below): nothing will be created either.Default:
False
force
If set, force the generation of HTML files, even if they have already been generated and are up to date. Note that you can combine this setting with
do_nothing
(see above).Default:
False
hide_index_html
If set,
/index.html
suffixes are removed from:- the
path
key that is automatically added in themd
binding passed to the template (see Template bindings (metadata) below); - URLs in the Sitemap (if a Sitemap is generated).
Default:
True
- the
ignore_files
A (possibly empty) sequence of regular expressions. If the path of a file matches one of these expressions, it will not be processed.
Default:
('.*\.DS_Store$', '.*~$')
locale_dir
The directory where translations are stored. Must be set to
None
if no such directory exists.Default:
'./locale'
.logger_level
The minimum level of the messages that will be logged. Must be one of
debug
,info
,warning
orerror
.Default:
'info'
.logger_path
The path to the log file. If set to
-
(a single dash), messages will be logged on the standard output. If a path is provided, it must be an absolute path.Default:
'-'
out_dir
The directory where the web site will be generated. This directory will be created if it does not exist.
Default:
'./www'
src_dir
The directory where source files live.
Default:
'./src'
sitemap
The name of the Sitemap file. Must be set to
None
if you do not want such a file to be generated.Default:
'sitemap.xml'
template
- The filename of the template to use. It must not be a relative or
absolute path to the file (like
/path/to/templates/layout.pt
) but only a filename (layout.pt
). template_dir
The directory where templates live.
Default:
'./templates'
Note
All directories (except www_dir
) are expected to exist. If you
do not need the feature, you must set the path to None
.
Also, each directory may be an absolute path or a relative path. If
it is a relative path and starts with ./
(more precisely a dot
followed by the separator on your operating system), the path is
supposed to be relative to the directory of the configuration
file. For example, './www'
will indicate a directory named
www
next to the configuration file. If the given path is a
relative path and does not start with ./
, then the path will be
relative to the working directory.
Default values can be found in the soho.defaults
module and reused
in your own configuration file:
import soho.defaults
ignore_files = soho.defaults.DEFAULT_IGNORE_FILES + (
# Sass source files and cache
'assets/css/src',
'assets/css/.sass-cache')
Command-line options¶
soho-build
accepts the following command-line options:
-a
,--assets-only
- See
assets_only
setting above. -c CONFIG_FILE
- Use
CONFIG_FILE
as the configuration file. By default, Soho uses a file namedsohoconf.py
in the working directory. -d
,--dry-run
,-do-nothing
- See
do_nothing
setting above. -f
,--force
- See
force
setting above. -h
,--help
- Show all command-line options.
-v
,--version
- Show the version number.
Template bindings (metadata)¶
For each source file that is processed, the template receives two bindings:
body
- The HTML fragment as a string.
md
A dictionary that contains the specific metadata of the source file (which inherits from the metadata of its directory, recursively) plus the following key:
path
The URL to the generated file relative to the root of the site. It always starts with a
/
.For example, the source file in
src/foo/bar/file.html
would have a path equal to/foo/bar/file.html
.