sphinxcontrib-fancybox 0.3.5
Sphinx "fancybox" extension
License: BSD

Sphinx "fancybox" extension.

Fancybox
========

.. warning::

    THIS PROJECT IS NOT MAINTAINED.
    PLEASE LOOK AT ``sphinxcontrib-images``:

    * https://pypi.python.org/pypi/sphinxcontrib-images

    * https://github.com/spinus/sphinxcontrib-images


Fancybox is adaptation of the jQuery plugin `fancybox <http://fancyapps.com/fancybox>`_ in version **2.1.5*. Note that version
Fancybox v2 and later are distributed under a 
`Creative Commons Attribution-NonCommercial 3.0 <http://creativecommons.org/licenses/by-nc/3.0/>`_
license. 

Documentation: `<http://spinus.github.com/sphinxcontrib-fancybox/>`_

github: `<http://github.com/spinus/sphinxcontrib-fancybox/>`_

PYPI: `<http://pypi.python.org/pypi/sphinxcontrib-fancybox/>`_

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

Instalation through pip: ::

    pip install sphinxcontrib-fancybox

or through github: ::

    git clone https://github.com/spinus/sphinxcontrib-fancybox
    cd sphinxcontrib-fancybox
    python setup.py install

Next, you have to add extension to `conf.py` in your sphinx project. ::

    extensions = [
              ...,
              'sphinxcontrib.fancybox',  
              ...]


Directives
----------

fancybox:
    
    Fancybox directive place a thumbnail of picture you selected, and add some
    `fancies`. If you click on image you get fullscreen box with that picture.

    Example: ::

        .. fancybox:: picture.png


    By default all images on one page are in the same group (you can navigate
    pressing `next` and `prev` buttons around this group).
    If you want to add picture to another group you have to set `group` 
    parameter, like: ::

        .. fancybox:: picture.png
            :group: group2


    You can change size of fancybox with 'width' and 'height' which are
    passed as you set it: ::

        .. fancybox:: picture.png
            :width: 100%
            :height: 2em


    You can add some description which will be rendered as `title` attribute::

        .. fancybox:: http://pictures.tld/picture.png

            Some description


    If you not set 'width' and 'height', defaults values are gathered from 
    `conf.py`. There are two parameters which you can adjust: ::

        fancybox_thumbnail_width
        fancybox_thumbnail_height


    Additionally you can set another css class with 'class' argument to 
    `fancybox` directive or set `fancybox_thumbnail_class` to add css class to 
    all `fancybox` directives.

    All fancybox JS config options you can pass as dict to `fancybox_config` in
    `conf.py` too.

    For examples please look to documentation conf.py.


TODO
----

* handling local files (not only remotes) (DONE)
* option to copying remote graphics as statics
* fallback for non html output (DONE)
* nested parsing fix
* JS should be handled only once, not on every image node
* width and height parameters (currently the thumbnail is set to 100x100px) (DONE)
* get default thumbnail size from config (DONE)
* generate thumbnails for big images 


Questions and suggestions
-------------------------

If you have some suggstions, patches, problems - please write an email or 
github message.