Sigal Release 1.0.0
Total Page:16
File Type:pdf, Size:1020Kb
Sigal Release 1.0.0 September 07, 2015 Contents 1 Themes & Demo 3 2 Documentation 5 2.1 Installation................................................5 2.2 Getting started..............................................6 2.3 Configuration...............................................7 2.4 Album information............................................ 11 2.5 Image information............................................ 11 2.6 Themes.................................................. 12 2.7 Plugins.................................................. 14 2.8 Contributing guidelines......................................... 18 2.9 Changelog................................................ 19 Python Module Index 25 i ii Sigal, Release 1.0.0 Sigal is yet another simple static gallery generator. It’s written in Python and it allows to build a static gallery of images with the following features: • Process directories recursively. • Generate HTML pages using jinja2 templates. • Relative links for a portable output. • Support themes, videos, EXIF tags, zip download. • Parallel processing. • MIT licensed. The idea behind Sigal is to ease the use of the javascript libraries like galleria. These libraries do a great job to display the images, Sigal does what is missing: resize images, create thumbnails, generate HTML pages. Sigal is compatible with Python 2.7 and 3.3+. Links : • Latest documentation on the website • Source, issues and pull requests on GitHub • Releases on PyPI • #sigal on Freenode, or with the webchat interface. • Mailing list at Librelist (Archives). Contents 1 Sigal, Release 1.0.0 2 Contents CHAPTER 1 Themes & Demo Sigal comes with three themes, based on the colorbox, galleria and photoswipe Javascript libraries: • colorbox demo • galleria demo • photoswipe demo 3 Sigal, Release 1.0.0 4 Chapter 1. Themes & Demo CHAPTER 2 Documentation 2.1 Installation Install the extension with one of the following commands: $ easy_install sigal or alternatively if you have pip installed: $ pip install sigal 2.1.1 Dependencies • Click • Jinja2 • Pilkit • Python Imaging Library (PIL / Pillow, see below) • Python Markdown 2.1.2 PIL or Pillow ? PIL is almost dead, the last release was in 2009. If possible you should prefer to use Pillow, a fork of PIL which is actively developped, with packaging improvements, Python 3 compatibility, etc. You can install Pillow with pip install Pillow, preferably in a virtualenv. To have JPG and PNG support, you must first install the developpement packages of libjpeg, freetype2 and zlib. • For Debian/Ubuntu, this is possible with: apt-get build-dep python-dev python-imaging Debian/Sid users can use the experimental python-imaging package that is built from Pillow source. • For Archlinux, there is a package for sigal in the AUR which already uses Pillow. 5 Sigal, Release 1.0.0 2.2 Getting started 2.2.1 How to Use Initialize To get started, just run sigal init which will copy an example configuration file in the current directory. All configuration values have a default; values that are commented out serve to show the default. Default values are specified when modified in this example config file. Build After adapting the configuration to your needs, put your images in a sub-directory and run sigal build <your images directory>. The next time you run sigal build, only the new images will be processed. You can use the -f flag to force the reprocessing of all the images. Images (resp. videos) that are smaller than the size specified by the img_size (resp. video_size) setting will not be resized. You may also want to know how to specify information about albums and images. Serve To visualize your gallery, you can use sigal serve which runs a basic web server. This server should only be used for local browsing, not in production. Another option is to use the index_in_url = True setting, which will add index.html to the urls to allow browsing without a server. 2.2.2 Help on the sigal build command $ sigal build [-h] [-d] [-v] [-f] [-c CONFIG] [-t THEME] [-n NCPU] [source] [destination] Required arguments: source Input directory destination Output directory (default: _build/) Optional arguments: -h, --help Show this help message and exit -f, --force Force the reprocessing of existing images and thumbnails -v, --verbose Show all messages -d, --debug Show all message, including debug messages -c CONFIG, --config CONFIG Configuration file (default: sigal.conf.py in the current working direc- tory) -t THEME, --theme THEME Specify a theme directory, or a theme name for the themes included with Sigal -n NCPU, --ncpu NCPU Number of cpu to use (default: all) 2.2.3 Help on the sigal serve command $ sigal serve [-c CONFIG] [-p PORT] [destination] Optional arguments: -c CONFIG, --config CONFIG Configuration file (default: sigal.conf.py in the current working direc- tory) 6 Chapter 2. Documentation Sigal, Release 1.0.0 -p PORT, --port PORT Port number to start the server on (default: 8000) destination Destination directory where the output of build is located (default: _build) 2.3 Configuration The configuration must be set in a sigal.conf.py file in the current directory. It can also be specified with the -c flag. An example file with explanations on the settings is available in sigal/templates/sigal.conf.py and is shown below. This file is copied to the current directory with the sigal init commmand. #-*- coding: utf-8 -*- # # All configuration values have a default; values that are commented out serve # to show the default. Default values are specified when modified in this # example config file # Gallery title. Can be set here or as the '--title' option of the `sigal # build` command, or in the 'index.md' file of the source directory. # The priority order is: cli option > settings file > index.md file # title = "Sigal test gallery" # --------------------- # General configuration # --------------------- # Source directory. Can be set here or as the first argument of the `sigal # build` command source='pictures' # Destination directory. Can be set here or as the second argument of the # `sigal build` command (default: '_build') # destination = '_build' # Theme : # - colorbox (default), galleria, photoswipe, or the path to a custom theme directory theme='galleria' # Author. Used in the footer of the pages and in the author meta tag. # author = '' # Use originals in gallery (default: False). If True, this will bypass all # processing steps (resize, auto-orient, recompress, and any plugin-specific # step). # Originals will be symlinked if orig_link = True, else they will be copied. # use_orig = False # ---------------- # Image processing (ignored if use_orig = True) # ---------------- # Size of resized image (default: (640, 480)) img_size=(800, 600) # Should we use openlayers to show a map of the images where possible? # This option only has an effect on the galleria theme for the while. # show_map = False 2.3. Configuration 7 Sigal, Release 1.0.0 # Pilkit processor used to resize the image # (see http://pilkit.readthedocs.org/en/latest/#processors) # - ResizeToFit: fit the image within the specified dimensions (default) # - ResizeToFill: crop THE IMAGE it to the exact specified width and height # - SmartResize: identical to ResizeToFill, but uses entropy to crop the image # - None: don't resize # img_processor = 'ResizeToFit' # Autorotate images # Warning: this setting is not compatible with `copy_exif_data` (see below), # because Sigal can't save the modified Orientation tag (currently Pillow can't # write EXIF). # autorotate_images = True # If True, EXIF data from the original image is copied to the resized image # copy_exif_data = False # Jpeg options # jpg_options = {'quality': 85, # 'optimize': True, # 'progressive': True} # -------------------- # Thumbnail generation # -------------------- # Generate thumbnails # make_thumbs = True # Subdirectory of the thumbnails # thumb_dir = 'thumbnails' # Prefix and/or suffix for thumbnail filenames (default: '') # thumb_prefix = '' # thumb_suffix = '.tn' # Thumbnail size (default: (200, 150)) # For the galleria theme, use 280 px for the width # For the colorbox and photoswipe theme, use 200 px for the width thumb_size=(280, 210) # Crop the image to fill the box # thumb_fit = True # Delay in seconds to avoid black thumbnails in videos with fade-in # thumb_video_delay = '0' # Keep original image (default: False) # keep_orig = True # Subdirectory for original images # orig_dir = 'original' # Use symbolic links instead of copying the original images # orig_link = False # Reverse sort for albums # albums_sort_reverse = False 8 Chapter 2. Documentation Sigal, Release 1.0.0 # Attribute of Media objects which is used to sort medias. 'date' can be used # to sort with EXIF dates. # medias_sort_attr = 'filename' # Reverse sort for medias # medias_sort_reverse = False # Filter directories and files. # The settings take a list of patterns matched with the fnmatch module on the # path relative to the source directory: # http://docs.python.org/2/library/fnmatch.html ignore_directories=[] ignore_files=[] # ------------- # Video options # ------------- # Video format # specify an alternative format, valid are 'webm' (default) and 'mp4' # video_format = 'webm' # Webm options # Options used in ffmpeg to encode the webm video. You may want to read # http://ffmpeg.org/trac/ffmpeg/wiki/vpxEncodingGuide # Be aware of the fact these options need to be passed as strings. If you are # using avconv (for example with Ubuntu), you will need to adapt the settings. # webm_options = ['-crf', '10', '-b:v', '1.6M', # '-qmin', '4', '-qmax',