seagull documentation - read the docs seagull documentation, release 1.0.dev1 seagull is an...

Download Seagull Documentation - Read the Docs Seagull Documentation, Release 1.0.dev1 Seagull is an open-source

Post on 20-Feb-2020

12 views

Category:

Documents

0 download

Embed Size (px)

TRANSCRIPT

  • Seagull Documentation Release 1.0.dev1

    Hajime Yamasaki Vukelic

    August 21, 2016

  • Contents

    1 Guide contents 3 1.1 Software requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.2 Installing Seagull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.3 First steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.4 Customizing the configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 1.5 Customizing the styling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 1.6 Customizing the templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

    i

  • ii

  • Seagull Documentation, Release 1.0.dev1

    Seagull is an open-source skinnable phot gallery app written in Python and released under the GNU General Public License.

    This guide explains how to start, customize, and deploy Seagull in a production environment. Since Seagull is rela- tively simple in design, most of the space will be spent on the customization aspect. The guide is written in the tutorial style to ease new users into the matter, but basic knowledge of Python, HTML, and CSS will definitely go a long way towards making the reading experience much easier.

    Contents 1

  • Seagull Documentation, Release 1.0.dev1

    2 Contents

  • CHAPTER 1

    Guide contents

    1.1 Software requirements

    In order to run Seagull on your machine, you will need to have a bunch of programs installed that Seagull depends on. Some of these programs are for running Seagull itself, some are for developing the skins. This section is divided into subsections so you can skip the parts you do not need at this time. You must, however, cover the Basics section.

    1.1.1 Basics

    At absolute minimum you will need to have Python 3.5 or newer installed. Seagull specifically uses features that were newly introduced in Python 3.5, so older versions will not work (not even older versions in the 3.x series).

    If you are on Linux, you should use your distro’s package manager to install Python. In some distributions (e.g., Arch Linux), the default python package is Python 3.x. On other distros, default is usually Python 2.x so the Python 3.x will use a package named python3 or something along those lines.

    Windows and Mac users can peruse the download page on python.org.

    Once Python is installed, check that you have the correct version. Run the following command in the command line (command prompt):

    > python --version Python 3.5.2

    In some instances, you may need to refer to Python 3.5 as python3 or even python3.5 in the command line:

    > python3 --version Python 3.5.2

    Throughout the rest of the guide, when you see python in the command examples, you will use the command name that worked for you, be it python or python3 (and the same applies to pip as you will see later on).

    Note: If your Linux distro does not ship the latest and greatest version, you will need to figure out a way to get the latest version. For older releases of Ubuntu, for example, follow this advice. Debian has Python 3.5 in the unstable branch. If you are going to eventually deploy Seagull yourself, it would probably be worthwhile to explore these upgrades now.

    If your Python install does not come with pip, the Python package manager, you will also need to install pip. The version of the pip package is not critical for using Seagull but asking for its version is a good way to test if it’s installed:

    3

    https://www.python.org/downloads/ http://askubuntu.com/a/682875/189682 https://packages.debian.org/sid/python3.5 https://packages.debian.org/sid/python3.5 https://pip.pypa.io/en/stable/ https://pip.pypa.io/en/stable/installing/

  • Seagull Documentation, Release 1.0.dev1

    > pip --version pip 8.1.2 from ..... (python 3.5)

    Make sure that it says ‘python 3.5’ in the result. If it says something like ‘python 2.7’ or any version other than 3.5, then you probably installed pip for the wrong version of Python. For example, on Linux, pip for Python 3.5 would be in a package named python3-pip or something similar. In some cases, the command itself may be different (e.g., pip3 instead of pip).

    1.1.2 Software needed for skin development

    If you intend to customize the built-in skins (but not strictly required if you just want to create a completely new skin), you will also need:

    • NodeJS and NPM for CoffeeScript support (see this guide)

    • Ruby and Ruby Gems for Compass support (see this guide)

    To verify the installs:

    > npm --version 3.10.3

    > gem --version 2.5.1

    Exact versions are not really important here. Once you have NodeJS, NPM, Ruby, and Ruby Gems installed, you will need to install CoffeeScript and Compass. To install CoffeeScript with NPM, run this command:

    > npm install --global coffee-script

    Next install Compass using Ruby Gem:

    > gem install compass

    You probably want to verify that these tools were installed correctly:

    > coffee --version CoffeeScript version 1.10.0

    > compass --version Compass 1.0.3 (Polaris) Copyright (c) 2008-2016 Chris Eppstein Released under the MIT License. Compass is charityware. Please make a tax deductable donation for a worthy cause: http://umdf.org/compass

    1.1.3 Tools for working on the documentation

    If you wish to hack at this guide, you will need to install Sphinx and the ReadTheDocs theme for Sphinx:

    > pip install sphinx sphinx-rtd-theme

    To verify that Sphinx was installed:

    > sphinx-build --version Sphinx (sphinx-build) 1.4.5

    4 Chapter 1. Guide contents

    http://coffeescript.org/ https://docs.npmjs.com/getting-started/installing-node http://compass-style.org/ http://www.ruby-lang.org/en/documentation/installation/

  • Seagull Documentation, Release 1.0.dev1

    1.1.4 Tools for working with the source code

    The Seagull source code can always be browsed through on GitHub, so making a local copy of the source code and tracking it is not strictly necessary. If you still wish to give it a try, here are the tools you will need:

    • Git

    • virtualenvwrapper

    1.2 Installing Seagull

    Once all the prerequisites are satisfied (see :doc:requirements), you can install Seagull itself.

    1.2.1 Install from GitHub

    To install Seagull on your computer as a package (as opposed to creating a local copy of the source, that is), you can install directly from the GitHub repository of the project:

    > pip install https://github.com/foxbunny/seagull/archive/master.zip

    If you need to know where it got installed, run the following command:

    > python -c 'import seagull; print(seagull.__appdir__)' /usr/lib/python3.5/site-packages/seagull # or on Windows: c:\python35\lib\site-packages\seagull

    1.2.2 Clone the source code

    If you installed the tools for working with the source code in the :doc:requirements section, you now get a chance to put them to use. First you will need to clone the Git repository:

    > git clone https://github.com/foxbunny/seagull.git Cloning into 'seagull'... remote: Counting objects: 418, done. remote: Compressing objects: 100% (194/194), done. emote: Total 418 (delta 226), reused 377 (delta 185), pack-reused 0 Receiving objects: 73% (306/418), 556.00 KiB | 260.00 KiB/s Receiving objects: 100% (418/418), 613.73 KiB | 260.00 KiB/s, done. Resolving deltas: 100% (226/226), done. Checking connectivity... done. > cd seagull > mkvirtualenv seagull Using base prefix '' New python executable in Installing setuptools, pip, wheel...done. > pip install -e . Obtaining file:// Collecting bottle==0.12.9 (from seagull==1.0.dev1) Collecting bottle-streamline==1.0 (from seagull==1.0.dev1) Collecting confloader==1.1 (from seagull==1.0.dev1) .... ....

    Later if you wish to update the source code do:

    1.2. Installing Seagull 5

    https://github.com/foxbunny/seagull https://git-scm.com/downloads http://virtualenvwrapper.readthedocs.io/en/latest/install.html

  • Seagull Documentation, Release 1.0.dev1

    > git reset --hard HEAD > git pull origin master

    Note: If you wish to learn more about Git, there is plenty of material on the Git homepage, in the documentation section, including introductory videos.

    1.2.3 Verifying the install

    To verify that seagull was installed correctly, you can run this command:

    > seagull --version 1.0.dev1

    1.3 First steps

    In this section, we’ll take Seagull for a quick step, and do some fairly basic ‘customization’, simply by manipulating the gallery folder.

    1.3.1 Ignition!

    Let’s quickly start up Seagull and see what that does. In your console, type:

    > seagull Starting Seagull Registering SIGINT handler Registering SIGTERM handler Preparing application to run Added JS bundle: app.js Added CSS bundle: app.css Quitting, no gallery directory '/tmp/seagull-gallery'

    So that was a bit underwhelming. It’s missing a gallery folder at its default location, which is /tmp/seagull-gallery (or C:\tmp\seagull-gallery on Windows). Thankfully, this is easy to fix. Let’s create the folder where it wants it and try again:

    > seagull Starting Seagull Registering SIGINT handler Registering SIGTERM handler Preparing application to run Added JS bundle: app.js Adde