Metadata-Version: 2.0
Name: prosopopee
Version: 0.1
Summary: excposure.co clone in a static web generating tool
Home-page: https://github.com/Psycojoker/prosopopee
Author: Laurent Peuch
Author-email: cortex@worlddomination.be
License: GPLv3+
Platform: UNKNOWN
Requires-Dist: jinja2
Requires-Dist: pyyaml

Prosopopee
==========

More or less a small clone of exposure.co in form of a static generator.
For those of you who don't know what exposure.co is, this more or less
allows you to organise you picture in a way that more or less tell a
story.

You can find example usages here:

-  http://media.faimaison.net/photos/galerie/
-  https://www.thebrownianmovement.org/
-  http://outside.browny.pink
-  http://such.life

Why?
====

I wanted to learn a bit of advanced css and I wanted to self-host my
data.

Requirements
------------

Installation needs Python, pip and virtualenv

::

    apt-get install python-pip python-virtualenv

Gallery building needs graphicsmagick library

::

    apt-get install graphicsmagick

Installation
------------

1. Create a virtualenv, and activate it

::

    virtualenv ve
    source ve/bin/activate

2. Download and install Prosopopee

::

    pip install prosopopee

Files organisation
------------------

The files organisation is quite simple:

-  in the root directory of your project you need a settings.yaml file
   that will contains the title and subtitle of your gallery
-  for each gallery you'll need a folder that also contains a
   settings.yaml file that will describe how to display the content on
   your gallery
-  and you put the pictures of the gallery inside the gallery folder

Root settings.yaml
~~~~~~~~~~~~~~~~~~

The root settings.yaml should contains 2 keys : one for the title of
your website and one for the subtitle. It should looks like that:

.. code:: yaml

    title: My exploration of the outside world
    sub_title: it's a scary place, don't go there

Menu
^^^^

It is possible to add a menu to your homepage that links to static
pages. To do so, add a ``menu`` key to your ``settings.yaml``, for
example:

.. code:: yaml

    menu:
      - about: "About Me"
      - contact: "Contact"

The first part (``about`` and ``contact``) here are the name of the
files (without the ``.yaml``) and the second part are the menu title
that will be displayed in the templates. So, here, you'll need to create
a ``about.yaml`` and a ``contact.yaml`` files in the root directory.
Their content are similar to galleries (see
`bellow <#gallery-settingsyaml>`__).

For example, this could be the content of ``contact.yaml``:

.. code:: yaml

    title: "Contact"
    sections:
      - type: text
        text: Some text, HTML <b>is allowed</b>.

Gallery settings.yaml
~~~~~~~~~~~~~~~~~~~~~

This settings.yaml will describe:

-  the title, subtitle and cover picture of your gallery that will be
   used on the homepage
-  if your gallery is public (if not, it will still be built but won't
   appear on the homepage)
-  the date of your gallery: this will be used on the homepage since
   **galleries are sorted anti chronologically** on it
-  the list of sections that will contains your gallery. A section will
   represent either one picture, a group of pictures or text. The
   different kind of sections will be explained in the next README
   section.

Here is an example:

.. code:: yaml

    title: Gallery title
    sub_title: Gallery sub-title
    date: 2016-01-15
    cover: my_cover_picture.jpg
    sections:
      - type: full-picture
        image: big_picture.jpg
        text:
          title: Big picture title
          sub_title: Some text
          date: 2016-01-15
      - type: pictures-group
        images:
          -
            - image1.jpg
            - image2.jpg
            - image3.jpg
          -
            - image4.jpg
            - image5.jpg
      - type: text
        text: Some text, HTML <b>is allowed</b>.
      - type: bordered-picture
        image: another_picture.jpg

And here is an example or a **private** gallery (notice the public
keyword):

.. code:: yaml

    title: Gallery title
    sub_title: Gallery sub-title
    date: 2016-01-15
    cover: my_cover_picture.jpg
    public: false
    sections:
        - ...

Different kind of sections
~~~~~~~~~~~~~~~~~~~~~~~~~~

A gallery is compose of a succession of sections as you can on this
`wonderfully totally uninteresting example
gallery <http://psycojoker.github.io/prosopopee/first_gallery/>`__ the
gallery is composed of 5 sections:

-  a full screen picture with text written on it
-  a picture with with borders around it
-  a group of 5 pictures
-  and a fullscreen picture without text on it this time

In your settings.yaml, a section will **always** have a type key that
will describe its kind and additional data. Underneath, the type key is
actually the name of an HTML template and the other data will be passed
to this template.

You can find all the sections templates here:
https://github.com/Psycojoker/prosopopee/tree/master/prosopopee/templates/sections

You often have an image key. You need to give it a path to the actual
file. By convention, those files are put inside your gallery folder but
this is not mandatory.

Full Screen picture with OR without text on it
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This display a full screen picture as shown in the `example
gallery <http://psycojoker.github.io/prosopopee/first_gallery/>`__ in
the first and last sections. How you should use it:

With text:

.. code:: yaml

      - type: full-picture
        image: big_picture.jpg
        text:
          title: Big picture title
          sub_title: Some text
          date: 2016-01-15

Without text:

.. code:: yaml

      - type: full-picture
        image: big_picture.jpg

Bordered picture
^^^^^^^^^^^^^^^^

This display a centered picture that is surrounded by white (the
background) as shown in the second position of the `example
gallery <http://psycojoker.github.io/prosopopee/first_gallery/>`__.

How to use it:

.. code:: yaml

      - type: bordered-picture
        image: another_picture.jpg

Group of pictures
^^^^^^^^^^^^^^^^^

This display a group of zoomable pictures on one or multiple lines as
shown on the forth position (after the text) of the `example
gallery <http://psycojoker.github.io/prosopopee/first_gallery/>`__.

.. code:: yaml

      - type: pictures-group
        images:
          -
            - image1.jpg
            - image2.jpg
            - image3.jpg
          -
            - image4.jpg
            - image5.jpg

Every sublist (the first level - represent a line).

**Know bug**: the images are left aligned, so if you don't put enough
images on a line, you'll have white space on the right.

Text
^^^^

This display some centered text as shown on the third position of the
`example
gallery <http://psycojoker.github.io/prosopopee/first_gallery/>`__. HTML
is allowed inside the text.

How to use it:

.. code:: yaml

      - type: text
        text: Some text, HTML <b>is allowed</b>.

Paragraph
^^^^^^^^^

This display a h2 title followed by text. HTML is allowed inside of the
text. If not title is declared, a separator is added.

How to use it:

.. code:: yaml

      - type: paragraph
        title: the title
        text: Some text, HTML <b>is allowed</b>.

HTML
^^^^

This section is for raw html that will be centered (for example:
inlining an OSM iframe).

How to use it:

.. code:: yaml

      - type: html
        html: <tag>some html stuff</html>

Panorama
^^^^^^^^

This display a very large pictures with a drag and drop posibility on
it.

How to use it:

.. code:: yaml

      - type: panorama
        image: 7.jpg

Example
~~~~~~~

As a recap, here is how the files of the example gallery are organised:

::

    example
          ├── settings.yaml
          └── first_gallery
              ├── settings.yaml
              └── stuff.png

The content of example/settings.yaml:

.. code:: yaml

    title: "Example gallery"

The content of example/first\_gallery/settings.yaml:

.. code:: yaml

    title: my first gallery
    sub_title: some subtitle
    date: 2015-12-08
    cover: stuff.png
    sections:
      - type: full-picture
        image: stuff.png
        text:
          title: Beautiful Title
          sub_title: pouet pouet
          date: 2015-12-08
      - type: bordered-picture
        image: stuff.png
      - type: text
        text: « voici plein de blabla à rajouter et <b>ceci est du gras</b> et encore plein plein plein plein de text car je veux voir comment ça va wrapper car c'est important et il faut pas que j'oublie de mettre des margins en % sinon ça va pas le faire alala là ça devrait aller »
      - type: pictures-group
        images:
          -
            - stuff.png
            - stuff.png
            - stuff.png
          -
            - stuff.png
            - stuff.png
      - type: full-picture
        image: stuff.png

Build the website
-----------------

**Note: You need to be in an activated virtualenv.**

In a folder containing the **root** settings.yaml file, simply do

::

    prosopopee

A ``build`` folder will be created in the current directory, containing
an index.html, static files (css & js) and pictures.

TODO
----

-  write documentation on how to overwrite the templates
-  allow to overwrite static files (for that we need a merge mechanism)
-  be mobile responsivepouetpouet (this mean css + resize pictures)
-  probably moar sections + allows to add legends on pictures or
   something like that
-  add ``--source`` & ``--destination`` command line options
-  add rss/atom

Licence
-------

GPLv3+

Credit
------

    16:57 <meornithorynque> et tu as besoin d'un nom ? 16:57
    <meornithorynque> genre n'importe quoi ? 16:57 <meornithorynque> je
    propose "Prosopopée"


