diff --git a/docs/build.rst b/docs/build.rst index 0224659..a85d2de 100644 --- a/docs/build.rst +++ b/docs/build.rst @@ -20,12 +20,12 @@ In a root folder launch this command:: prosopopee preview -After you can check your website on http://localhost:9000 +Then, you can check your website at http://localhost:9000 Deployment ---------- -Prosopopee can upload your website with rsync, for do it run:: +Prosopopee can upload your website with rsync, to do so, run:: prosopopee deploy diff --git a/docs/configuration.rst b/docs/configuration.rst index af9f3b9..e2a5e2d 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -1,24 +1,22 @@ 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 + * in the root directory of your project you need a settings.yaml file that contains the title and subtitle of your gallery + * for each gallery you need a folder that also contains a settings.yaml file that describes how to display the content in your gallery * and you put the pictures of the gallery inside the gallery folder * or other directory, in the gallery became an index (so pictures won't be display, only cover of child gallery) 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:: +The root settings.yaml should contain 2 keys: one for the title of your website and one for the subtitle. It should look 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.` +It can also optionally contain a menu and global settings. Menu ____ @@ -42,23 +40,22 @@ For example, this could be the content of `settings.yaml` in `about` folder:: 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 -case you didn't specified "public: false" you'll **need** to specify a "cover:" +"public: false" if you don't want to list this page on the homepage. If +you don't specify "public: false" you **need** to specify a "cover:" entry like any other gallery. **NOTE**: expect the "static: " option to disappear 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. +Global settings can be put 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 :: +Currently a `gm` setting key allows to customize the default GraphicsMagick's behaviour. It looks like:: title: Gallery settings: @@ -72,17 +69,17 @@ Currently a `gm` settings key allows to customize the default GraphicsMagick's b 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) + * `auto-orient` changes 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 - * `progressive` converts classic baseline JPEG files to progressive JPEG, and interlace PNG/GIF files (improve the page loading impression, slightly reduce file size) + * `resize` can be used to resize the full-size version of pictures. By default, input image size is preserved + * `progressive` converts classic baseline JPEG files to progressive JPEG, and interlaces PNG/GIF files (improves the page loading impression, slightly reduces file size) Any GraphicsMagick setting can be customized on a per-image basis (either `cover` or `image`, see below). -Video convertor +Video converter ~~~~~~~~~~~~~~~ -Prosopopée can use ffmpeg or libav and if you want you can customize the settings:: +Prosopopée can use ffmpeg or libav and each can be configured if needed:: title: Gallery settings: @@ -99,16 +96,16 @@ Prosopopée can use ffmpeg or libav and if you want you can customize the settin The meaning of the currently supported FFMEG or LIBAV's settings is as follows : - * `binary` the binary you will use for convert the video (ffmpeg or avconv) - * `loglevel` Set the logging level used by the library - * `format` Force input or output file format - * `resolution` Set frame size - * `vbitrate` Set video bitrate - * `abitrate` Set audio bitrate - * `audio` Set the audio codec - * `video` Set the video codec - * `extension` Set the extension of output file - * `other` Set different options if you need more + * `binary` sets the binary to use to convert the video (ffmpeg or avconv) + * `loglevel` sets the logging level used by the library + * `format` forces input or output file format + * `resolution` sets frame size + * `vbitrate` sets video bitrate + * `abitrate` sets audio bitrate + * `audio` sets the audio codec + * `video` sets the video codec + * `extension` sets the extension of output file + * `other` sets different options if you need more example for MP4:: @@ -121,39 +118,38 @@ example for MP4:: video: "libx264" extension: mp4 - - Light Mode ~~~~~~~~~~ -For enabled the light mode:: +To enable the light mode:: title: Gallery settings: light_mode: true -With this option Prospopee make a sub directory with light version of your gallery. -This light gallery use less JS, picture in low size etc.. +With this option Prospopee makes a subdirectory with light version of your gallery. +This light gallery uses less JS, pictures in low size, etc. -For access to this light gallery, add /light in the url of the gallery. +To access this light gallery, add /light at the end of the URL of the gallery. -If you want only light theme you can see below. +If you want only light theme, see :ref:`themes`. Night Mode ~~~~~~~~~~ -For enabled the night mode only available for exposure theme (default theme):: +To enable the night mode, which is only available for exposure theme (default theme):: title: Gallery settings: night_mode: true -After that you will can choose dark theme or light theme during visiting the website. +After that you will be able to choose between dark theme or light theme when visiting the website. +.. themes: Themes ~~~~~~ -Prosopopée has a support for various themes. As for now, only 3 themes are available: +Prosopopée supports different themes. As for now, only 3 themes are available: * the default one called "exposure" * "material" based on materialcss @@ -167,12 +163,11 @@ To specify the theme, add the "theme" key in your "settings" key or your 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:: +By default Prosopopée uses CC-BY-SA for all the content. If you want to use another licence, +you need to add a "licence" key in **root** settings.yaml. For example:: title: Gallery licence: @@ -182,68 +177,67 @@ you need add key in **root** settings.yaml. For example:: 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+:: +If you want to enable content sharing on social networks, add the "share" key in **root** settings.yaml. For example:: title: Gallery share: true url: "http://prosopopee.com" +By default you can share on facebook, twitter, pinterest, google+. + RSS ~~~ -For activate the RSS you need add this key in **root** settings.yaml:: +To activate the RSS feed you need to add the "rss" key in **root** settings.yaml:: title: Gallery rss: true url: "http://prosopopee.com" - Open Graph Meta ~~~~~~~~~~~~~~~ -For activate the Open Graph Meta you need add this key in **root** settings.yaml:: +To activate the Open Graph Meta you need to add the "og" key in **root** settings.yaml:: title: Sur les chemins settings: og: true -Optionnal: You need use description and lang key in settings gallery. +You can also specify a description and a language ("lang" key) for a gallery. -for more informations about Open Graph http://ogp.me/ +For more information about Open Graph http://ogp.me/ Deployment ~~~~~~~~~~ -If you wanna configure the deployement of your website by rsync:: +If you want to configure the deployment of your website with rsync:: title: Gallery settings: deploy: - ssh: true (optional need for ssh) - username: username (optional need for ssh) - hostname: server.com (optional need for ssh) + ssh: true (optional, for ssh) + username: username (optional, for ssh) + hostname: server.com (optional, for ssh) dest: /var/www/website/build/ - others: --delete-afte (optional) + others: --delete-after (optional) -Reverse -~~~~~~~ +Reverse order +~~~~~~~~~~~~~ -Normally Prosopopee build the gallery index in Anti-chronological, if you wanna reverse it:: +Normally Prosopopee builds the gallery index in anti-chronological. If you want to have it in chronological order, use the "reverse" key:: settings: reverse: true -Is option can be use too in gallery settings if you use multi level gallery:: +This option can also be used in a gallery settings.yaml if you use multi-level galleries:: title: Multi level gallery reverse: true - Password access ~~~~~~~~~~~~~~~ -If you wanna protect all the website by password:: +If you want to protect all the website by password:: title: Gallery password: my_super_password @@ -254,10 +248,10 @@ 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 + * the tags, which are 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. + * the date of your gallery that will be used on the homepage since **galleries are sorted anti-chronologically** + * the list of sections that represents your gallery. A section represents either one picture, a group of pictures or text. The different kinds of sections will be explained in the next README section. Example _______ @@ -307,7 +301,7 @@ And here is an example of a **private** gallery (notice the ``public`` keyword): Advanced settings ----------------- -Images handling +Image handling _______________ Images go into the `cover` or `image` keys. @@ -332,10 +326,9 @@ by:: Password access _______________ -You can protect access of gallery with password:: +You can restrict access to a gallery with a password:: title: Gallery title sub_title: Gallery sub-title password: my_super_password - diff --git a/docs/index.rst b/docs/index.rst index cae693f..2209fa9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,9 +1,8 @@ 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. +More or less a small clone of exposure.co in form of a static website generator. +For those of you who don't know what exposure.co is, it allows you to tell a story with your pictures. You can find example usages here: diff --git a/docs/install.rst b/docs/install.rst index 231399e..38c8359 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -7,16 +7,16 @@ Requirements Ubuntu/Debian ~~~~~~~~~~~~~ -Installation needs Python, pip and virtualenv:: +We need Python, pip and virtualenv:: apt-get install python-pip python-virtualenv -Gallery building needs graphicsmagick library:: +and graphicsmagick library for building the gallery:: - # graphicsmagick need to have a version of gcc-5-base in 5.3.1 + # graphicsmagick requires to have the 5.3.1 version of gcc-5-base apt-get install graphicsmagick -An video convertor like ffmpeg:: +A video converter like ffmpeg:: apt-get install ffmpeg @@ -24,32 +24,29 @@ or:: apt-get install libav-tools -The deployment need rsync:: +For deployment, we need rsync:: apt-get install rsync Mac ~~~ -Installation needs Brew:: +We need Brew:: /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" - -Gallery building needs graphicsmagick library:: +and graphicsmagick library for building the gallery:: brew install graphicsmagick - -An video convertor like ffmpeg:: +A video converter like ffmpeg:: brew install ffmpeg -The deployment need rsync:: +For deployment, we need rsync:: brew install rsync - Installation in virtualenv -------------------------- @@ -73,5 +70,4 @@ Run:: docker run --rm -v $(pwd):/site prosopopee - More informations https://hub.docker.com/r/beudbeud/prosopopee/ diff --git a/docs/sections.rst b/docs/sections.rst index 8ca16e5..41a2e71 100644 --- a/docs/sections.rst +++ b/docs/sections.rst @@ -3,20 +3,20 @@ Sections A gallery is composed of a succession of sections as you can see on this `wonderfully totally uninteresting example -gallery `_ the gallery is -composed of 5 sections: +gallery `_. This gallery is +split in 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 +* and a full-screen 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: +You can find all the section templates here: https://github.com/Psycojoker/prosopopee/tree/master/prosopopee/themes/exposure/templates/sections @@ -29,7 +29,7 @@ ___________________ This displays a full screen picture as shown in the `example gallery `_ in the first -and last sections. How you should use it : +and last sections. How you should use it: With text:: @@ -45,9 +45,8 @@ Without text:: - type: full-picture image: big_picture.jpg - -If you want fixed backgroup use can use this optionnal option (only with the exposure theme):: +If you want a fixed background you can use this option (only with the exposure theme):: - type: full-picture fixed: true @@ -55,7 +54,7 @@ If you want fixed backgroup use can use this optionnal option (only with the exp Bordered picture ________________ -This displays a centered picture that is surrounded by white (the background) as +This displays a centred picture that is surrounded by white (the background) as shown in the second position of the `example gallery `_. @@ -81,16 +80,16 @@ gallery `_:: - image4.jpg - image5.jpg -The first level `-` represent a line of pictures. -The second level `-` represent the list of images in this line. +The first level `-` represents a row of pictures. +The second level `-` represents 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. +**Known bug**: the images are left aligned, so if you don't put enough images on +a row, you'll have some white space on the right. Text ____ -This displays some centered text as shown on the third position of the `example +This displays some centred text as shown on the third position of the `example gallery `_. HTML is allowed inside the text. @@ -102,7 +101,7 @@ How to use it:: Paragraph _________ -This displays a h2 title followed by text. HTML is allowed inside of the text. +This displays a h2 title followed by text. HTML is allowed inside the text. If no title is declared, a separator is added. How to use it:: @@ -111,7 +110,7 @@ How to use it:: title: the title text: Some text, HTML is allowed. -Since 0.5 you can add a floating image in paragraph:: +Since version 0.5 you can add a floating image in the paragraph:: - type: paragraph title: the title @@ -120,12 +119,12 @@ Since 0.5 you can add a floating image in paragraph:: float: right size: 150px -By default if you don't set float and size the image will be on left with a size of 250px +By default if you don't set float and size the image will be on left with a size of 250px. HTML ____ -This section is for raw html that will be centered (for example: inlining an OSM iframe). +This section is for raw html that will be centred (for example: inlining an OSM iframe). How to use it:: @@ -135,8 +134,7 @@ How to use it:: Panorama ________ - -This displays a very large picture with a drag-and-drop possibility on it. +This displays a very large picture that can be drag-and-dropped. How to use it:: @@ -146,18 +144,17 @@ How to use it:: Audio _____ -This section is for add audio file with HTML5 player.:: +This section is for adding an audio file playable with the HTML5 player.:: - type: audio title: Title of song image: song.ogg color: "#000" (optional) - Author ______ -This section is for describe the author of the story:: +This section is for describing the author of the story:: - type: author name: Adrien Beudin @@ -170,7 +167,7 @@ This section is for describe the author of the story:: Iframe ______ -This section make your embeds iframe responsive:: +This section makes your embed iframes responsive:: - type: iframe name: @@ -178,7 +175,7 @@ This section make your embeds iframe responsive:: Quote _____ -For use quoteblock easily:: +To use quote blocks easily:: - type: quote text: This is a quote @@ -186,12 +183,12 @@ For use quoteblock easily:: Advanced options ________________ -Images caption +Image caption ~~~~~~~~~~~~~~ -Prosopopée has a support of caption in images, you can use it on bordered-picture and pictures-group. +Prosopopée supports captions for images, you can use it on bordered-picture and pictures-group. -Exemple on bordered-picture:: +Example on bordered-picture:: - type: bordered-picture image: another_picture.jpg @@ -213,15 +210,15 @@ And on pictures-group:: Background settings ~~~~~~~~~~~~~~~~~~~ -For all section you can define the background. +For all sections, you can define the background. -Exemple for background color:: +Example for background colour:: - type: bordered-picture background: "#555" image: another_picture.jpg -or you can use picture:: +or you can use a picture:: - type: text background: "url(background_picture.jpg)" @@ -230,9 +227,9 @@ or you can use picture:: Text color settings ~~~~~~~~~~~~~~~~~~~ -For text, html and paragraph section you can define the text color. +For text, html and paragraph sections, you can also define the text colour. -Exemple:: +Example:: - type: bordered-picture color: "#333" @@ -240,14 +237,14 @@ Exemple:: Video support ~~~~~~~~~~~~~ -For bordered-picture, full-picture and pictures-group it's possible to use +For bordered-picture, full-picture and pictures-group, it's possible to use video instead of pictures. You have to specify with the "type" key that it's a video. The video will be converted using either ffmpeg or avconv (depending on the one specified in the settings, ffmpeg being the default one). -Exemple for pictures-group:: +Example for pictures-group:: - type: pictures-group images: @@ -260,7 +257,7 @@ Exemple for pictures-group:: - image3.jpeg - image4.jpeg -Exemple for bordered-picture:: +Example for bordered-picture:: - type: bordered-picture image: @@ -279,7 +276,7 @@ And for full-picture:: date: 2016-03-11 date_end: 2016-03-25 -You can also use a video for a gallery cover:: +You can also use a video as a gallery cover:: title: pouet sub_title: plop diff --git a/docs/theming.rst b/docs/theming.rst index 88dd339..9ad5ce0 100644 --- a/docs/theming.rst +++ b/docs/theming.rst @@ -4,19 +4,18 @@ Theming Custom css and js ----------------- -You can add easily css code and js code. You need create custom.css or custom.js +You can easily add css code and js code. You just need to create a custom.css or custom.js in root directory. Override template ----------------- -If you wanna override template, you need create a "templates" directory and create your own template. +If you want to override a template, you need to create a "templates" directory and add your own template. * home page : index.html * gallery page: gallery-index.html -And for override sections you need create file in "templates/sections". - +And to override sections you need to create a file in "templates/sections". Create theme ------------