Metadata-Version: 1.0
Name: prosopopee
Version: 0.3
Summary: exposure.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+
Description: 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
        
        It can also optionally contain a menu and global settings.
        
        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"
              - first_gallery: "My first gallery"
              - http://twitter.com: "Twitter"
        
        For example, this could be the content of ``settings.yaml`` in ``about``
        folder:
        
        .. code:: yaml
        
            title: "About"
            static: true
            public: false
            sections:
              - type: text
                text: Some text, HTML <b>is allowed</b>.
        
        You can use the ``static`` option to get a template closer to the one of
        the homepage that is better suited for a static page. You'll need to
        specify "public: false" if you don't want to list this page on the
        homepage. On you case you didn't specified "public: false" you'll
        **need** to specify a "cover:" entry like any other gallery.
        
        **NOTE**: except the "static: " option to disepear quite soon for a more
        generic approach to "choose your page style".
        
        Global settings
        ^^^^^^^^^^^^^^^
        
        Global settings can be set in your root ``settings.yaml``, under the
        ``settings`` key.
        
        GM
        ''
        
        Currently a ``gm`` settings key allows to customize the default
        GraphicsMagick's behavior. It looks like :
        
        .. code:: yaml
        
            settings:
              gm:
                quality: 75
                auto-orient: True
                strip: True
                resize: 50%
        
        The meaning of the currently supported GraphicsMagick's settings is as
        follows : \* ``quality`` allows to customize the compression level of
        thumbnails (between 0 and 100) \* ``auto-orient`` change the orientation
        of pictures so they are upright (based on corresponding EXIF tags if
        present) \* ``strip`` removes all profiles and text attributes from the
        image (good for privacy, slightly reduce file size) \* ``resize`` can be
        used to resize the fullsize version of pictures. by default, input image
        size is preserved
        
        Any GraphicsMagick setting can be customized on a per-image basis
        (either ``cover`` or ``image``, see below).
        
        Themes
        ''''''
        
        Prosopopée has a support for various themes. As for now, only 2 themes
        are available:
        
        -  the default one called "exposure"
        -  "material" based on materialcss
        
        To specify the theme, add the "theme" key in your "settings" key or your
        **root** settings.yaml. For example:
        
        .. code:: yaml
        
            title: My exploration of the outside world
            sub_title: it's a scary place, don't go there
            settings:
              theme: material
        
        Licence
        '''''''
        
        By default Prosopopée use CC-BY-SA for all the content, if you want use
        a another licence you need add key in **root** settings.yaml. For
        example:
        
        .. code:: yaml
        
            licence:
               name: WTFPL
               url: "http://www.wtfpl.net/txt/copying/"
        
        Share
        '''''
        
        If you want enable the share content on social network, add key in
        **root** settings.yaml. For example: By defaut you can share on
        facebook, twitter, pinterest, google+.
        
        .. code:: yaml
        
            share: true
            url: "http://prosopopee.com/"
        
        Gallery settings.yaml
        ~~~~~~~~~~~~~~~~~~~~~
        
        This settings.yaml will describe:
        
        -  the title, subtitle and cover picture of your gallery that will be
           used on the homepage
        -  the tags is optional
        -  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
            tags:
              - #yolo
              - #travel
            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:
                - ...
        
        Images handling
        ^^^^^^^^^^^^^^^
        
        Images go into the ``cover`` or ``image`` keys. Each image individual
        processing settings can be customized to override the default
        GraphicsMagick settings defined (or not) in the root ``settings.yaml``.
        
        This is done by putting the image path into a ``name`` key, and adding
        specific processing settings afterwards.
        
        For example, you can replace :
        
        .. code:: yaml
        
            image: image1.jpg
        
        by:
        
        .. code:: yaml
        
            image:
              name: image1.jpg
              quality: 90
              strip: False
              auto-orient: False
        
        Different kind of sections
        ~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        A gallery is composed of a succession of sections as you can see 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 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 displays 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
                  date_end: 2016-01-24 (Optional)
        
        Without text:
        
        .. code:: yaml
        
              - type: full-picture
                image: big_picture.jpg
        
        Bordered picture
        ^^^^^^^^^^^^^^^^
        
        This displays 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 displays a group of zoomable pictures on one or multiple lines as
        shown on the fourth 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
        
        The first level ``-`` represent a line of pictures. The second level
        ``-`` represent the list of images in this 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 displays 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 displays a h2 title followed by text. HTML is allowed inside of the
        text. If no 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 displays a very large picture with a drag-and-drop possibility on
        it.
        
        How to use it:
        
        .. code:: yaml
        
              - type: panorama
                image: 7.jpg
        
        Author
        ^^^^^^
        
        This section is for describe the author of the story.
        
        .. code:: yaml
        
              - type: author
                name: Adrien Beudin
                text: Some text
                image: IMG_20150725_200941.jpg
                twitter: beudbeud (Optional)
                facebook: beudbeud (Optional)
                website: plop.fr (Optional)
        
        Images caption
        ~~~~~~~~~~~~~~
        
        Prosopopée has a support of caption in images, you can use it on
        bordered-picture and pictures-group.
        
        Exemple on bordered-picture :
        
        .. code:: yaml
        
              - type: bordered-picture
                image: another_picture.jpg
                text: This is a caption
        
        And on pictures-group
        
        .. code:: yaml
        
              - type: pictures-group
                images:
                  -
                    - name: image1.jpg
                      text: This is a caption
                    - image2.jpg
                    - image3.jpg
                  -
                    - image4.jpg
                    - image5.jpg
        
        Background settings
        ~~~~~~~~~~~~~~~~~~~
        
        For all section you can define the background.
        
        Exemple for background color
        
        .. code:: yaml
        
              - type: bordered-picture
                background: "#555"
                image: another_picture.jpg
        
        or you can use picture
        
        .. code:: yaml
        
              - type: text
                background: "url(background_picture.jpg)"
                text: Some text
        
        Text color settings
        ~~~~~~~~~~~~~~~~~~~
        
        For text, html and paragraph section you can define the text color.
        
        Exemple
        
        .. code:: yaml
        
              - type: bordered-picture
                color: "#333"
        
        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"
        
        Authors
        -------
        
        By chronological order:
        
        -  `Bram <http://worlddomination.be>`__, launched the project
        -  `Kload <https://github.com/Kloadut>`__
        -  `opi <https://github.com/opi>`__
        -  `taziden <https://www.libre-parcours.net/>`__
        -  `beudbeud <https://github.com/abeudin>`__
        -  `CapsLock <https://blog.legeox.net/>`__
        -  `Julien Malik <https://github.com/julienmalik>`__
        
        
        
        
        CHANGELOG
        =========
        
        0.3 the "beudbeud release" (2016-04-13)
        ---------------------------------------
        
        -  caption support on bordered picture and pictures group
           https://github.com/Psycojoker/prosopopee#images-caption by beudbeud
        -  configure licence https://github.com/Psycojoker/prosopopee#licence in
           footer by beudbeud
        -  possibility to use a range for the full picture date
           https://github.com/Psycojoker/prosopopee#full-screen-picture-with-or-without-text-on-it
           by beudbeud
        -  Update material theme by beudbeud
        -  social share https://github.com/Psycojoker/prosopopee#share by
           beudbeud
        -  Define background and text color of section
           https://github.com/abeudin/prosopopee#background-settings by beudbeud
        
        0.2 (2016-02-23)
        ----------------
        
        -  a lot new contributors stepped in, see
           https://github.com/Psycojoker/prosopopee#authors
        -  possibility to specify an (optional) menu
           https://github.com/Psycojoker/prosopopee#menu made by beudbeud
        -  configure Graphics Magick options on a global or per images fashion
           https://github.com/Psycojoker/prosopopee#gm and
           https://github.com/Psycojoker/prosopopee#images-handling by capslock
           and jmk
        -  support for various themes and a new material theme in addition of
           the default one https://github.com/Psycojoker/prosopopee#gm by
           beudbeud
        -  tags support in gallery settings
           https://github.com/Psycojoker/prosopopee#gallery-settingsyaml by
           beudbeud
        -  introduce internal CACHE format version to avoid breaking build when
           changing it
        
        0.1 (2016-02-09)
        ----------------
        
        -  First pypi release
        
        
Platform: UNKNOWN
