path: root/README.md

   
Trac Wiki converted to Pelican Markdown
The Trac Wiki that used to hold this site has been converted to a
wiki-like setup using git, Markdown, Pelican, and m.css.

git repository behind this Wiki.
Pelican documentation.
m.css documentation.

The git repository is configured to generate the web content from the
Markdown automatically upon receiving a git push.
linkchecker may also be
useful in validating the generated content.
The Makefile in this directory makes it easy to test out changes to
the content before pushing them, eg:
make all check server


will generate the content, run the result through linkchecker, then
start up a web server on the name and port specified in the Makefile
(which you can override with the HTTP_HOST and HTTP_PORT
variables) to let you browse the result.  Feel free to experiment on
your own copy: there are almost certainly things we could do better
within the Pelican framework, maybe you'll figure them out for us.
The upstream repository is configured to run Pelican automatically on
push and install the result, and to refuse the push if something fails
to compile.  It is of course possible to mess things up in ways that
won't cause compilation to fail, so don't do that. :)
As with all Cryptech git repositories, all commits to this repository
must be signed by a known key.
For completeness, here's how this hooks into git: hang something like
the following script off the upstream repository's update hook:
#!/bin/sh -

set -xe

ref="$1"
oldrev="$2"
newrev="$3"

branch=refs/heads/master
repo=/some/where/safe.git
work=/some/where/else
dest=/some/where/visible

if test "$ref" = "$branch"
then
    export CRYPTECH_WIKI_PRODUCTION_BUILD=true
    cd $work
    git --git-dir $repo --work-tree $work checkout --force $newrev
    git --git-dir $repo --work-tree $work submodule update --init
    pelican --output website --settings pelicanconf.py --fatal errors content
    chmod -R a+rX $work
    rsync -a --delete website/ $dest/
fi


Setting --git-dir is probably unnecessary, since the hook will
inherit the $GIT_DIR environment variable, but it's also harmless.
$CRYPTECH_WIKI_PRODUCTION_BUILD allows our pelicanconf.py to
default to developer settings while automatically using production
settings when built using the git hook.