Welcome to govlab-static-tools’s documentation!¶

govlab-static-tools (or simply govlabstatic) is a collection of tools that make it slightly easier to build static websites for GovLab.

GovLab static sites make use of staticjinja and Jinja2 for the generation of HTML content and SASS for CSS.

Philosophy¶

This package is generally intended to be used as glue that exposes the functionality of existing third-party libraries for core functionality when possible. It’s also intended to provide testing tools out-of-the-box.

Installation¶

govlab-static-tools supports Python 2.7.

Installation can be done via pip:

$ pip install govlab-static-tools

You’ll also want to install Ruby SASS (libsass is not currently supported). To verify this, try running sass --version at the command-line.

Example¶

See the code for the example project, which contains the following build.py file in its root directory:

import os

import staticjinja
from govlabstatic.cli import Manager

manager = Manager(
    site_name='example site',
    site=staticjinja.make_site(outpath='site'),
    sass_src_path=os.path.join('sass', 'styles.scss'),
    sass_dest_path=os.path.join('site', 'static', 'styles', 'styles.css')
)

if __name__ == '__main__':
    manager.run()

Running python build.py --help will output:

usage: build.py [-h] {build,runserver,test} ...

Static site generator for example site

positional arguments:
  {build,runserver,test}
    build               Build the static site.
    runserver           Run development server. This builds the static site,
                        and rebuilds necessary files whenever changes are
                        detected.
    test                Run test suite. Currently, this builds the site and
                        checks links.

optional arguments:
  -h, --help            show this help message and exit

For a more detailed example, see the source for the GovLab website.

Enabling Link Checking¶

Running python build.py test will only work if you have the pylinkchecker package installed. Unfortunately, at the time of this writing, the package is not available on PyPi, and must be installed via git with:

$ pip install git+git://github.com/mtlevolio/pylinkchecker.git#egg=pylinkchecker

Developer API¶

class govlabstatic.cli.Manager(site_name, sass_src_path, sass_dest_path, site)[source]¶

Command-line interface manager for static site generation and associated tools.

Parameters:	site_name – The name of the site, e.g. `'GovLab Academy Website'` or `'www.mysite.com'`. sass_src_path – The path to SASS source, e.g. `'sass/styles.scss'`. sass_dest_path – The path to compile SASS source to, e.g. `'static/styles/styles.css'`. site – A `staticjinja.Site` object representing the site to build.

parser¶: An argparse.ArgumentParser responsible for parsing command-line arguments. Feel free to add to this via argh.assembling.add_commands() to add new commands to your CLI.

watcher¶: A govlabstatic.watcher.Watcher instance used to watch directories for changes.

run()[source]¶: Runs the command-line interpreter.

class govlabstatic.watcher.Watcher[source]¶

Encapsulates the watching of directories and files and taking actions when they change.

observer¶: A watchdog.observers.api.BaseObserver instance. Feel free to schedule the watching of new paths and reacting to changes in them as needed.