diff --git a/docs/themes.rst b/docs/themes.rst index b68c7f0..3057c2e 100644 --- a/docs/themes.rst +++ b/docs/themes.rst @@ -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 %} - Download archive - {% 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: diff --git a/sigal/gallery.py b/sigal/gallery.py index 475e490..4650cff 100644 --- a/sigal/gallery.py +++ b/sigal/gallery.py @@ -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) diff --git a/sigal/writer.py b/sigal/writer.py index b582a7b..c5ab54c 100644 --- a/sigal/writer.py +++ b/sigal/writer.py @@ -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