forks/sigal
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Documentation

Browse Source
This commit is contained in:
Simon Conseil
2014-03-04 00:18:07 +01:00
parent 09ff3b9b53
commit cc40cbc18b
3 changed files with 90 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
docs/themes.rst
View File

@@ -26,59 +26,44 @@ Variables
You can use the following variables in your template:
``albums``
List of ``album`` objects. An ``album`` object has the following attributes:
- ``album.name``
- ``album.title``
- ``album.url``
- ``album.thumb``
``breadcrumb``
List of ``(url, title)`` tuples defining the current breadcrumb path.
``index_title``
Name of the index. This is either the directory name or the title specified
in the ``index.md``.
``index_url``
URL to the index page.
``medias``
List of ``media`` objects. A ``media`` object has the following attributes:
- ``media.type``: Either ``"img"`` or ``"vid"``.
- ``media.file``: Location of the resized image.
- ``media.thumb``: Location of the corresponding thumbnail image.
- ``media.big``: If not None, location of the unmodified image.
- ``media.exif``: If not None contains a dict with the most common tags. For
more information, see :ref:`simple-exif-data`.
- ``media.raw_exif``: If not ``None``, it contains the raw EXIF tags.
``meta`` and ``description``
Meta data and album description. For details how to annotate your albums
with meta data, see :doc:`album_information`.
``theme.name``
Name of the currently used theme.
in the ``index.md`` of the ``source`` directory.
``settings``
The entire dictionary from ``sigal.conf.py``. For example, you could use
this to output an optional download link for zipped archives:
.. code-block:: jinja
{% if settings.zip_gallery %}
<a href="{{ settings.zip_gallery }}">Download archive</a>
{% endif %}
The entire dictionary from ``sigal.conf.py``.
``sigal_link``
URL to the Sigal homepage.
``zip_gallery``
If not None, it contains the location of a zip archive with all original
images of the corresponding directory.
``theme.name``, ``theme.url``
Name and url of the currently used theme.
Then the current album that is rendered in the HTML file is represented by an
:class:`~sigal.gallery.Album` object, and the following attributes are
available in the template: ``albums``, ``breadcrumb``, ``description``,
``index_url``, ``medias``, ``meta``, ``zip``, ``title``.
.. autoclass:: sigal.gallery.Album
:members:
:undoc-members:
:inherited-members:
``medias`` contains the list of all medias in the album (represented by the
:class:`~sigal.gallery.Image` and :class:`~sigal.gallery.Video` objects,
inherited from :class:`~sigal.gallery.Media`).
.. autoclass:: sigal.gallery.Media
:members:
:undoc-members:
.. autoclass:: sigal.gallery.Image
:members:
:undoc-members:
.. autoclass:: sigal.gallery.Video
:members:
:undoc-members:
.. _simple-exif-data:

66
sigal/gallery.py
View File

@@ -46,6 +46,22 @@ from .writer import Writer
class Media(UnicodeMixin):
"""Base Class for media files.
Attributes:
- ``type``: ``"image"`` or ``"video"``.
- ``filename``: Filename of the resized image.
- ``thumbnail``: Location of the corresponding thumbnail image.
- ``big``: If not None, location of the unmodified image.
- ``exif``: If not None contains a dict with the most common tags. For more
information, see :ref:`simple-exif-data`.
- ``raw_exif``: If not ``None``, it contains the raw EXIF tags.
"""
type = ''
extensions = ()
def __init__(self, filename, path, settings):
self.filename = filename
@@ -69,6 +85,9 @@ class Media(UnicodeMixin):
@property
def big(self):
"""Path to the original image, if ``keep_orig`` is set (relative to the
album directory).
"""
if self.settings['keep_orig']:
return get_orig(self.settings, self.filename)
else:
@@ -76,8 +95,10 @@ class Media(UnicodeMixin):
@property
def thumbnail(self):
# if thumbnail is missing (if settings['make_thumbs'] is False)
"""Path to the thumbnail image (relative to the album directory)."""
if not os.path.isfile(self.thumb_path):
# if thumbnail is missing (if settings['make_thumbs'] is False)
if self.type == 'image':
generator = image.generate_thumbnail
elif self.type == 'video':
@@ -91,6 +112,7 @@ class Media(UnicodeMixin):
class Image(Media):
"""Gather all informations on an image file."""
type = 'image'
extensions = ('.jpg', '.jpeg', '.JPG', '.JPEG', '.png')
@@ -101,6 +123,7 @@ class Image(Media):
class Video(Media):
"""Gather all informations on a video file."""
type = 'video'
extensions = ('.MOV', '.mov', '.avi', '.mp4', '.webm', '.ogv')
@@ -113,6 +136,21 @@ class Video(Media):
class Album(UnicodeMixin):
"""Gather all informations on an album.
Attributes:
:var description_file: Name of the Markdown file which gives information
on an album
:ivar index_url: URL to the index page.
:ivar output_file: Name of the output HTML file
:ivar meta: Meta data from the Markdown file.
:ivar description: description from the Markdown file.
For details how to annotate your albums with meta data, see
:doc:`album_information`.
"""
description_file = "index.md"
output_file = 'index.html'
@@ -133,7 +171,7 @@ class Album(UnicodeMixin):
self.dst_path = join(settings['destination'], path)
self.logger = logging.getLogger(__name__)
self.get_metadata()
self._get_metadata()
# Create thumbnails directory and optionally the one for original img
check_or_create_dir(self.dst_path)
@@ -146,6 +184,7 @@ class Album(UnicodeMixin):
# optionally add index.html to the URLs
self.url_ext = self.output_file if settings['index_in_url'] else ''
self.url = self.name + '/' + self.url_ext
self.index_url = os.path.relpath(settings['destination'],
self.dst_path) + '/' + self.url_ext
@@ -172,8 +211,8 @@ class Album(UnicodeMixin):
def __iter__(self):
return itertools.chain(self.images, self.videos)
def get_metadata(self):
""" Get album metadata from `description_file` (`index.md`):
def _get_metadata(self):
"""Get album metadata from `description_file` (`index.md`):
-> title, thumbnail image, description
@@ -201,17 +240,23 @@ class Album(UnicodeMixin):
@property
def medias(self):
"""List of all medias in the album (:class:`~sigal.gallery.Image` and
:class:`~sigal.gallery.Video`).
"""
return self.images + self.videos
@property
def albums(self):
"""List of :class:`~sigal.gallery.Album` objects for each
sub-directory.
"""
root_path = self.path if self.path != '.' else ''
return [self.gallery.albums[join(root_path, path)]
for path in self.subdirs]
@property
def thumbnail(self):
"""Check the thumbnail image for a given path, find one if possible."""
"""Path to the thumbnail of the album."""
# stop if it is already set and a valid file
if self._thumbnail and isfile(join(self.src_path, self._thumbnail)):
@@ -254,8 +299,9 @@ class Album(UnicodeMixin):
@property
def breadcrumb(self):
"""Paths to upper directories (with titles and links)."""
"""List of ``(url, title)`` tuples defining the current breadcrumb
path.
"""
if self.path == '.':
return []
@@ -275,6 +321,12 @@ class Album(UnicodeMixin):
@property
def zip(self):
"""Make a ZIP archive with all media files and return its path.
If the ``zip_gallery`` setting is set,it contains the location of a zip
archive with all original images of the corresponding directory.
"""
zip_gallery = self.settings['zip_gallery']
if zip_gallery:
archive_path = join(self.dst_path, zip_gallery)

4
sigal/writer.py
View File

@@ -106,8 +106,8 @@ class Writer(object):
'url': os.path.relpath(self.theme_path, album.dst_path)},
}
for attr in ('albums', 'breadcrumb', 'index_url', 'medias', 'zip',
'title'):
for attr in ('albums', 'breadcrumb', 'description', 'index_url',
'medias', 'meta', 'zip', 'title'):
ctx[attr] = getattr(album, attr)
return ctx