Reformatted with automated tools and minor fixes.

docs/METADATA.md

@@ -0,0 +1,77 @@
+# METADATA #
+
+## FORMAT ##
+
+Metadata is stored as a JSON file which allows C-likecomments.
+
+Metadata is loaded from the top down, so each parent from the root can impart metadata on children. Children can explitily nullify parent metadata by
+assigning it to undefined.
+
+## STORAGE ##
+
+On-disk meatdata is stored as a file along side the non-metadata file with the extension '.meta', for example the file 'foo.thtml' would have a metadata file as 'foo.thtml.meta'. Metadata for directories (which gets applied to all contents of that directory) is stored in .meta in the directory.
+
+## DEFAULT KEYS AND VALUES ##
+
+All files define the following keys by default:
+
+relpath
+:  The relative path to the root of the site, useful for prepending to image `src=` and other resource paths such as CSS files and fonts in order to maintain locally viewable output.
+file_name
+:  The local path of the file
+file_path
+:  The full path to the file from the root
+dir
+:  The directory to the path from root for this file
+os-path
+:  The native OS path to this file
+guessed-type
+:  The guessed mime-type of the file
+stat
+:  A tree of stat() values in a dictionary, without the ST_ prefix, and with lowercase keys.
+templates
+:  The path to the template files.
+uuid
+:  A UUID for this file based on its path and a specified `uuid-oid-root` metadata
+build-time
+:  The time stamp for the build time
+
+Files can also explicitly override these which are set to empty defaults:
+
+mime-type
+:  Either the specified mime-type or guessed type if undefined.
+template
+:  The full path to the template file
+dir-template
+:  The full path to the filesystem template
+title
+:  A title for this object derived from the template, metadata or other sources.
+summary
+:  A summary of the file contents.
+description
+:  A description of file contents.
+
+Trees have some metadata that projects should probably override (generally in their top-level .meta):
+
+uuid-oid-root
+:  A string added to the beginning of the path that identifies this site, used for deriving OID UUIDs.
+author
+:  The full name of the author of this site (should also be overridden per-file if necessary).
+author_email
+:  The email of the author of this site (see above)
+site_root
+:  The full URL for the root of this web site used for links and whatnot, with ending slash.
+
+Special Keys that can be defined, these change the processing in predictable ways:
+
+type
+: Define that the file that this metadata is applied to as a specific type from the type mapping table. Useful values are `passthrough` and `templatable` with obvious outcomes.
+wildcard_metadata
+: Define a dictionary of file globs (patterns which match files such as `*.txt`), with the value being a dictionary of additional metadata to apply to the matched files. This is generally
+defined at the top level of the project to make certain file patterns treated as special without having to give them their own metadata.
+
+
+## CACHING STRATEGY ##
+
+The tree is traversed from the top down, each node in the tree is stat(). The mtime walue is compared to the mtime stored in the cache dict for that node. If it is newer, the metadata
+is loaded again, and the tree continues to traverse.

docs/Patterns.md

@@ -0,0 +1,5 @@
+# Patterns for Site Design #
+
+These are some simple patterns for things commonly needed in websites of various kinds.
+
+##

docs/TemplateFunctions.md

@@ -0,0 +1,113 @@
+# Template Functions #
+
+These are functions exposed to the templates which perform various useful actions for the site designer.
+
+## get_file_list ##
+
+Return a list of file names based on a wildcard glob, matched against the root of the project.
+
+Prototype: `get_file_list(file_glob, sort_order, reverse, limit) -> [files]`
+
+Arguments:
+* file_glob: A standard file glob, for example `*.txt` matches all files that end in `.txt` in the root of the project. (default: `*`)
+* sort_order: A string of either `file_path`, `file_name`, `ctime`, `mtime`, `size` and `ext` (default: `ctime`)
+* reverse: whether the sort is reversed (default: False)
+* limit: The number of entries to return from the top of the list, 0 for unlimited (default: `0`)
+
+Returns:
+* A list of file names.
+
+## get_file_name ##
+
+Return the filename that will result from processing the specified file based on the processors that it will be passed through.
+
+Prototype: `get_file_name(file) -> outfile`
+
+Arguments:
+* file: The name of a file, with path, from root.
+
+Returns:
+* outfile: The name of the file, with path, that will result from processing.
+
+## get_file_content ##
+
+Return the rendered content of specified file. Caution: Can result in infinite loops if two templates include each other.
+
+Prototype: `get_file_content(file) -> content`
+
+Arguments:
+* file: The name of the input file, with path, from root.
+
+Returns:
+* content: the contents that result from passing the specified file through its processors.
+
+## get_raw ##
+
+Return the raw contents of a source file. It is specifically not passed through any processing.
+
+Prototype: `get_raw(file) -> content`
+
+Arguments:
+* file: The name of the input file, with path, from root.
+
+Returns:
+* content: the raw contents of the input file
+
+## get_file_metadata ##
+
+Return the metadata tree associated with a particular file.
+
+Prototype: `get_file_metadata(file) -> metadata`
+
+Arguments:
+* file: the name of an input file, with path, from root
+
+Returns:
+* metadata: A dictionary of metadata loaded from the file tree.
+
+## get_time_iso8601 ##
+
+Return the date/time stamp in ISO 8601 format for a given time_t timestamp for UTC.
+
+Prototype: `get_time_iso8601(timestamp) -> timestamp`
+
+Arguments:
+* timestamp: A time_t integer or float, in seconds since Jan 1 1970.
+
+Returns:
+* timestamp: A string in ISO8601 format of the date and timestamp, in the UTC timezone.
+
+## get_date_iso8601 ##
+
+Return the date stamp in ISO 8601 format for a given time_t timestamp for UTC.
+
+Prototype: `get_date_iso8601(timestamp) -> timestamp`
+
+Arguments:
+* timestamp: A time_t integer or float, in seconds since Jan 1 1970.
+
+Returns:
+* timestamp: A string in ISO8601 format of the date stamp, in the UTC timezone.
+
+## pygments_get_css ##
+
+Return a blob of CSS produced from Pygments for a given `style`.
+
+Prototype: `pygments_get_css(style) -> css`
+
+Arguments:
+* style (optional): A style identifier for the Pygments' HTMLFormatter.
+
+Returns:
+* css: A string of styles as returned by Pygments' HTMLFormatter.
+
+## pygments_markup_contents_html ##
+
+Format a code fragment with Pygments
+
+Prototype: `pygments_markup_contents_html(input, filetype, style) -> html`
+
+Arguments:
+* input: A string containing the code to format (either literal, or imported with get_raw()).
+* filetype: A string describing which lexer to use.
+* style (optional) A style identifier for Pygments' HTMLFormatter.

docs/project-layout.md

@@ -0,0 +1,71 @@
+# Project Layout #
+
+It is recommended that in general your project for PixyWerk2 site be layed out like:
+```
+project_top/
+   Makefile              - Convenient for building your site
+   src/                  - All "source" pages are contained in here.
+     .meta               - Top-level default metadata is set here
+	 index.cont          - The content part of the index page
+	 index.cont.meta     - A metadata json file for the index, specifically.
+     templates/          - Templates go in here
+       default.jinja2    - Default template that will be used if none are specified
+   publish/              - The path the build process will create, where the post-processed files go.
+```
+
+
+## Makefile ##
+
+Makefile is suggested, but not essential, for encapsulating your build commands to produce your
+site. Something as simple as:
+
+```
+build: src/templates/* src/*
+	python -mpixywerk2 src publish
+```
+
+## src/ ##
+
+This is the top level path that all of your templates, page fragments, images, etc. will be stored. This is basically the "source code" for your site.
+
+## src/.meta ##
+
+This is the top level metadata that is used as the default for all subsidiary metadata. It is in JSON format (with JS style comments). See <METADATA.md> for more information.
+
+Example .meta file:
+
+```
+{
+	"title": "My Website", // this is the default title applied if none are specified
+	"author": "Super Web Dude",
+	"site_root": "http://example.com",
+	"uuid-oid-root": "example.com-", // this is used to generate UUIDs
+}
+```
+
+## src/templates/ ##
+
+Templates are all stored here, as this is the search path for Jinja.
+
+## templates/default.jinja2 ##
+
+If a page specifies a `template` metadata key, the named template is used, however, if not this template is used. Generally speaking this is a complete HTML file, with the `{{ content }}` template string placed where the content of subsidiary pages will be embedded.
+
+A simple default.jinja2 example:
+
+```
+<!DOCTYPE html>
+<html>
+<head>
+<title>{{ metadata.title }}</title>
+</head>
+<body>
+{{content}}
+</body>
+</html>
+```
+
+
+## publish/ ##
+
+This is arbitrary, and will be created by pixywerk at build time, but it will be the root path that should be published to your web server.