add readthedocs documentation
This commit is contained in:
Adrien Beudin
parent
2668afd17b
commit
3d6a1fa452
13
docs/authors.rst
Normal file
13
docs/authors.rst
Normal file
@ -0,0 +1,13 @@
|
|||||||
|
Authors
|
||||||
|
=======
|
||||||
|
|
||||||
|
By chronological order:
|
||||||
|
|
||||||
|
* Bram, launched the project
|
||||||
|
* Kload
|
||||||
|
* opi
|
||||||
|
* taziden
|
||||||
|
* beudbeud
|
||||||
|
* CapsLock
|
||||||
|
* Julien Malik
|
||||||
|
|
||||||
11
docs/build.rst
Normal file
11
docs/build.rst
Normal file
@ -0,0 +1,11 @@
|
|||||||
|
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.
|
||||||
33
docs/changelog.rst
Normal file
33
docs/changelog.rst
Normal file
@ -0,0 +1,33 @@
|
|||||||
|
Changelog
|
||||||
|
=========
|
||||||
|
|
||||||
|
0.4 (unreleased)
|
||||||
|
|
||||||
|
* RSS https://prosopopee.readthedocs.org/en/latest/configuration.html#rss by beudbeud
|
||||||
|
|
||||||
|
0.3.1 (2016-04-13)
|
||||||
|
|
||||||
|
* fix: cover date was hidden by default, this was a backward breaking behavior
|
||||||
|
|
||||||
|
0.3 the "beudbeud release" (2016-04-13)
|
||||||
|
|
||||||
|
* caption support on bordered picture and pictures group https://prosopopee.readthedocs.org/en/latest/sections.html#advanced-options by beudbeud
|
||||||
|
* configure licence https://prosopopee.readthedocs.org/en/latest/configuration.html#licence in footer by beudbeud
|
||||||
|
* possibility to use a range for the full picture date https://prosopopee.readthedocs.org/en/latest/sections.html#full-screen-picture by beudbeud
|
||||||
|
* Update material theme by beudbeud
|
||||||
|
* social share https://prosopopee.readthedocs.org/en/latest/configuration.html#share by beudbeud
|
||||||
|
* Define background and text color of section https://prosopopee.readthedocs.org/en/latest/sections.html#advanced-options by beudbeud
|
||||||
|
|
||||||
|
0.2 (2016-02-23)
|
||||||
|
|
||||||
|
* a lot new contributors stepped in, see https://prosopopee.readthedocs.org/en/latest/authors.html
|
||||||
|
* possibility to specify an (optional) menu https://prosopopee.readthedocs.org/en/latest/configuration.html#menu made by beudbeud
|
||||||
|
* configure Graphics Magick options on a global or per images fashion https://prosopopee.readthedocs.org/en/latest/configuration.html#gm and https://prosopopee.readthedocs.org/en/latest/configuration.html#images-handling by capslock and jmk
|
||||||
|
* support for various themes and a new material theme in addition of the default one https://prosopopee.readthedocs.org/en/latest/configuration.html#themes by beudbeud
|
||||||
|
* tags support in gallery settings https://prosopopee.readthedocs.org/en/latest/configuration.html#example by beudbeud
|
||||||
|
* introduce internal CACHE format version to avoid breaking build when changing it
|
||||||
|
|
||||||
|
0.1 (2016-02-09)
|
||||||
|
|
||||||
|
* First pypi release
|
||||||
|
|
||||||
197
docs/configuration.rst
Normal file
197
docs/configuration.rst
Normal file
@ -0,0 +1,197 @@
|
|||||||
|
Configuration
|
||||||
|
=============
|
||||||
|
|
||||||
|
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::
|
||||||
|
|
||||||
|
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::
|
||||||
|
|
||||||
|
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::
|
||||||
|
|
||||||
|
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 ::
|
||||||
|
|
||||||
|
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::
|
||||||
|
|
||||||
|
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::
|
||||||
|
|
||||||
|
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+::
|
||||||
|
|
||||||
|
share: true
|
||||||
|
url: "http://prosopopee.com"
|
||||||
|
|
||||||
|
RSS
|
||||||
|
~~~
|
||||||
|
|
||||||
|
For activate the RSS you need add this key in **root** settings.yaml::
|
||||||
|
|
||||||
|
rss: 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.
|
||||||
|
|
||||||
|
Example
|
||||||
|
_______
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
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)::
|
||||||
|
|
||||||
|
title: Gallery title
|
||||||
|
sub_title: Gallery sub-title
|
||||||
|
date: 2016-01-15
|
||||||
|
cover: my_cover_picture.jpg
|
||||||
|
public: false
|
||||||
|
sections:
|
||||||
|
- ...
|
||||||
|
|
||||||
|
Advanced settings
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
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::
|
||||||
|
|
||||||
|
image: image1.jpg
|
||||||
|
|
||||||
|
by::
|
||||||
|
|
||||||
|
image:
|
||||||
|
name: image1.jpg
|
||||||
|
quality: 90
|
||||||
|
strip: False
|
||||||
|
auto-orient: False
|
||||||
44
docs/example.rst
Normal file
44
docs/example.rst
Normal file
@ -0,0 +1,44 @@
|
|||||||
|
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``::
|
||||||
|
|
||||||
|
title: "Example gallery"
|
||||||
|
sub_title: some subtitle
|
||||||
|
|
||||||
|
The content of ``example/first_gallery/settings.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
|
||||||
50
docs/index.rst
Normal file
50
docs/index.rst
Normal file
@ -0,0 +1,50 @@
|
|||||||
|
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 allows you to tell a story with your pictures.
|
||||||
|
|
||||||
|
You can find example usages here:
|
||||||
|
|
||||||
|
* http://surleschemins.fr
|
||||||
|
* 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 instead of using exposure.co.
|
||||||
|
|
||||||
|
Licence
|
||||||
|
=======
|
||||||
|
|
||||||
|
GPLv3+
|
||||||
|
|
||||||
|
Credit
|
||||||
|
======
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
> 16:57 <meornithorynque> et tu as besoin d'un nom ?<br>
|
||||||
|
> 16:57 <meornithorynque> genre n'importe quoi ?<br>
|
||||||
|
> 16:57 <meornithorynque> je propose "Prosopopée"
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Documentation
|
||||||
|
=============
|
||||||
|
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 2
|
||||||
|
|
||||||
|
install
|
||||||
|
configuration
|
||||||
|
sections
|
||||||
|
example
|
||||||
|
build
|
||||||
|
authors
|
||||||
|
changelog
|
||||||
25
docs/install.rst
Normal file
25
docs/install.rst
Normal file
@ -0,0 +1,25 @@
|
|||||||
|
Installation
|
||||||
|
============
|
||||||
|
|
||||||
|
Requirements
|
||||||
|
-------------
|
||||||
|
|
||||||
|
Installation needs Python, pip and virtualenv::
|
||||||
|
|
||||||
|
apt-get install python-pip python-virtualenv
|
||||||
|
|
||||||
|
Gallery building needs graphicsmagick library::
|
||||||
|
|
||||||
|
apt-get install graphicsmagick
|
||||||
|
|
||||||
|
Installation in virtualenv
|
||||||
|
--------------------------
|
||||||
|
|
||||||
|
1. Create a virtualenv, and activate it::
|
||||||
|
|
||||||
|
virtualenv ve
|
||||||
|
source ve/bin/activate
|
||||||
|
|
||||||
|
2. Download and install Prosopopee::
|
||||||
|
|
||||||
|
pip install prosopopee
|
||||||
193
docs/sections.rst
Normal file
193
docs/sections.rst
Normal file
@ -0,0 +1,193 @@
|
|||||||
|
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
|
||||||
|
___________________
|
||||||
|
|
||||||
|
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::
|
||||||
|
|
||||||
|
- 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::
|
||||||
|
|
||||||
|
- 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::
|
||||||
|
|
||||||
|
- 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/)::
|
||||||
|
|
||||||
|
- 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::
|
||||||
|
|
||||||
|
- 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::
|
||||||
|
|
||||||
|
- 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::
|
||||||
|
|
||||||
|
- 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::
|
||||||
|
|
||||||
|
- type: panorama
|
||||||
|
image: 7.jpg
|
||||||
|
|
||||||
|
Author
|
||||||
|
______
|
||||||
|
|
||||||
|
This section is for describe the author of the story::
|
||||||
|
|
||||||
|
- type: author
|
||||||
|
name: Adrien Beudin
|
||||||
|
text: Some text
|
||||||
|
image: IMG_20150725_200941.jpg
|
||||||
|
twitter: beudbeud (Optional)
|
||||||
|
facebook: beudbeud (Optional)
|
||||||
|
website: plop.fr (Optional)
|
||||||
|
|
||||||
|
Advanced options
|
||||||
|
________________
|
||||||
|
|
||||||
|
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::
|
||||||
|
|
||||||
|
- type: bordered-picture
|
||||||
|
image: another_picture.jpg
|
||||||
|
text: This is a caption
|
||||||
|
|
||||||
|
And on pictures-group::
|
||||||
|
|
||||||
|
- 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::
|
||||||
|
|
||||||
|
- type: bordered-picture
|
||||||
|
background: "#555"
|
||||||
|
image: another_picture.jpg
|
||||||
|
|
||||||
|
or you can use picture::
|
||||||
|
|
||||||
|
- 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::
|
||||||
|
|
||||||
|
- type: bordered-picture
|
||||||
|
color: "#333"
|
||||||
|
|
||||||
Loading…
x
Reference in New Issue
Block a user