If DELETE_OUTPUT_DIRECTORY is set to True, all files and directories are
deleted from the output directory. There are, however, several reasons
one might want to retain certain files/directories and avoid their
deletion from the output directory. One such use case is version control
system data: a versioned output directory can facilitate deployment via
Heroku and/or allow the user to easily revert to a prior version of the
site without having to rely on regeneration via Pelican.
This change introduces the OUTPUT_RETENTION setting, a tuple of
filenames that will be preserved when the clean_output_dir function in
pelican.utils is run. Setting OUTPUT_RETENTION = (".hg", ".git") would,
for example, prevent the relevant VCS data from being deleted when the
output directory is cleaned.
The change to the "make clean" task in 764a2cf from "rm -rf" to instead
relying on GNU "find" appears to have broken cross-platform portability,
likely causing problems on *BSD and other platforms. This commit reverts
that change back to the previous "rm -rf" behavior.
This change removes the "clean" task from the "html" and "regenerate"
tasks in the default Makefile generated by pelican-quickstart. The
previous behavior ignored whether the DELETE_OUTPUT_DIRECTORY
setting was set to True or not and deleted everything in the output
directory every time the "make html" or "make regenerate" task was run.
In addition to violating the Principle of Least Astonishment, there was
also the potential for data loss if the user wasn't careful when
defining the output directory location in the Makefile.
The new behavior therefore relies primarily on the
DELETE_OUTPUT_DIRECTORY setting to control if and when the output
directory is cleaned. The default settings and Makefile generated by the
pelican-quickstart command, for example, no longer clean the output
directory when the "make html" task is run. If the user wants to change
this behavior and have the output directory cleaned on every "make html"
run, the recommended method would be to set DELETE_OUTPUT_DIRECTORY to
True in pelicanconf.py. Alternatively, the user can manually run "make
clean", with the caveat that the output directory and its contents will
be entirely destroyed, including any otherwise to-be-retained files or
folders specified in the OUTPUT_RETENTION setting. It is for that reason
that relying on the DELETE_OUTPUT_DIRECTORY setting is instead
recommended.
As before, DELETE_OUTPUT_DIRECTORY is set to True in the publishconf.py
settings file generated by the pelican-quickstart script. This way, any
potentially old and irrelevant files will be automatically removed
before the latest version of the site is transferred to the production
server environment.
In summary, this change allows for the sanest possible default settings,
while still allowing end users to customize output cleaning to their
preferred behavior with a minimum of confusion.
I'd added them earlier to test that a configuration edit could
preserve the original output locations. However, it is likely that
you have quite a number of static files, and we shouldn't recommend
listing explicit paths for all of them. With this configuration
change, the pictures will be copied into the output directory using
their original relative path (e.g. `pictures/Fat_Cat.jpg` without the
`static`). Any |filename|-style links will be updated automatically.
If you *want* the pictures to end up in a `static` directory, it's
easier to just organize your source that way.
The broken code came from my 1d4d86c (settings: Rework the
LESS_GENERATOR removal warning for easy extension, 2013-03-24), where
I put formatting placeholders ({}) into the warning message, but
forgot to fill them in :/.
All paths should be relative to Generator.path unless we're actively
accessing the filesystem. This makes the argument less ambiguous, so
we have less likelyhood of joining paths multiple times.
In situations where I've cleared ARTICLE_DIR, I've done so to ensure
that there are no directories that will override the DEFAULT_CATEGORY
due to USE_FOLDER_AS_CATEGORY.
We no longer instantiate the Static object in the StaticGenerator, so
we can't set the save_as argument anymore. If you want to adjust the
output path, use the upcoming EXTRA_PATH_METADATA setting.
The assorted generators all use read_file() to read in the file
contents and metadata. Previously, they sometimes parse additional
metadata, fire off signals, and initialize a pelican.contents.Content
subclass on their own. We can reduce duplicated code and increase
consistency by shifting all that stuff into read_file() itself, and
this commit is a step in that direction.
We'll get better failure messages if we use an assertion method that
understands the comparison we're trying to make. If you make the
comparison by hand and assertTrue(), you don't get much constructive
feedback ;).
Support the forms listed by the W3C [1]. I also removed the
'%Y-%d-%m' form, which can be confused with the '%Y-%m-%d' ISO form.
The new ISO forms can use 'Z' to designate UTC or '[+-]HHMM' to
specify offsets from UTC. Other time zone designators are not
supported.
The '%z' directive has only been supported since Python 3.2 [2], so if
you're running Pelican on Python 2.7, you're stuck with 'Z' for UTC.
Conveniently, we get ValueErrors for both invalid directives and
data/format missmatches, so we don't need special handling for the 2.7
case inside get_date().
[1]: http://www.w3.org/TR/NOTE-datetime
[2]: http://bugs.python.org/issue6641
If a setting exists in DEFAULT_CONFIG, assume it will be there
(instead of checking and/or providing a local default). The earlier
code was split between the two idioms, which was confusing.
This avoids harcoding test-specific overrides, and makes it easy to
setup a settings dictionary based on DEFAULT_CONFIG for testing.
Because you can trust Pelican to use settings based on DEFAULT_CONFIG,
you are free to go about using:
settings[my_key]
instead of:
settings.get(my_key, some_fallback)
or:
if my_key in settings:
...
if you know that `my_key` is in DEFAULT_CONFIG.
Setting migration is something that will happen for multiple settings,
and the more we can standardize the reporting procedure, the easier it
will be to add new warnings.
This dictionary is accessed by plugins (like `summary`) which add new
settings, so it should be public (i.e. no prefixed underscore).
The changed name length would have led to a re-indenting of the
default contents anyway, so I shifted them all to four spaces.
AdReaderTest.test_article_with_asc_extension() has had duplicate
checks on the expected metadata since it was created by 49f481e3 (Add
asciidoc reader support, 2013-10-28). This commit removes the
duplicate entry.
