Building RST Documentation

Note: The following guide has only been tested on *nix-based systems (Ubuntu, Debian, OS X, etc). You may need to amend the instructions and example commands for your environment. This guide has not been tested on Windows.

System Dependencies

You must install the python interpreter, the pip package manager, the make build tool, and the git distributed version control system. The following shows examples of installing these system dependencies on a few common operating systems.

# debian-based (ubuntu, mint, etc) using apt
apt install python python-pip make git

# centos and red hat enterprise linux using yum
yum install epel-release
yum install python python-pip make git

# fedora using dnf
dnf install python2 python2-pip make git

# archlinux using pacman
pacman -S python2 python2-pip make git

# opensuse using zypper and pip installation script
zypper install python make git
wget https://bootstrap.pypa.io/get-pip.py
sudo python get-pip.py
rm get-pip.py

# mac osx using homebrew
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
brew install python make git

For additional guidance on installing python or pip, reference the python download guide or pip installation guide, respectively.

Python Build Environment

Setting up the build environment involves ensuring you have a copy of both the imagine bundle and symfony documentation, as well as creating a virtual environment to install the required python package requirements.

Enter Imagine Bundle Repository

We first need to enter the root path of the imagine bundle repository repository. You can either clone a new copy or enter the local working copy you have on your system.

# IF you do not have a copy, clone a new one and enter it
git clone https://github.com/liip/LiipImagineBundle.git imagine-bundle
cd imagine-bundle

# OR if you already have a local working copy simply enter it
cd /home/user/project/my-local-imagine-copy

Clone Symfony Docs and Link Imagine Bundle

Clone a copy of the official Symfony documentation repository and enter the newly created directory. Inside the symfony documentation repository, create a symbolic link pointing to this bundle's RST documentation root directory and reference the Imagine Bundle from within the index.rst file of the Symfony documentation.

# clone the symfony documentation repo and enter it
git clone https://github.com/symfony/symfony-docs symfony-docs
cd symfony-docs

# create symbolic link to imagine bundle repo
ln -s ../Resources/doc/ liip-imagine-bundle

# add imagine reference to symfony's index file
echo -ne "\n.. toctree::\n    :hidden:\n\n    liip-imagine-bundle/index\n" >> index.rst

Setup Build Environment

This guide uses virtualenv to create an isolated python environment, which avoids conflicting package versions, permissions, and other common dependency issues. Use the python package manager to install virtualenv and then use it to create and activate a new "virtual environment".

# install virtualenv package
python -m pip install --user virtualenv

# use virtualenv to create a virtual environment
python -m virtualenv ../.venv

# enter the newly created virtual environment
source ../.venv/bin/activate

Install Build Requirements

Use the python package manager and the Symfony documentation build requirements file to install the required build dependencies.

# install python build requirements
pip install -r _build/.requirements.txt

Source Compilation and Testing

The RST documentation files are compiled to HTML. Use the make command to compile the documentation and a browser of your choice to view the locally compiled HTML files. Accepted changed to this project's documentation will ultimately be published to the official Symfony website at symfony.com/doc/master/bundles/LiipImagineBundle.

Building the Documentation

Ensure you are still at the Symfony documentation repository root directory and call make with the following arguments to compile the RST files to HTML.

# build the documentation using the make command
make -C _build SPHINXOPTS=-nW html

You should receive no build errors or warnings. If you are testing your own local modification of the RST files for a new PR or other documentation contribution, notate the location of the error or warning and fix the source, as appropriate. All changes you submit to the imagine bundle repository must compile cleanly.

Viewing the Resulting HTML

You can view the resulting HTML documentation for Imagine Bundle by viewing liip-imagine-bundle/index.html in a browser of your choice. Using Google Chrome you can view the compiled documentation using the following:

# open the compiled html using google chrome
google-chrome _build/html/liip-imagine-bundle/index.html

Revisions

• 2016-10-01: If you would like to follow our previous guide, which did not use virtualenv, view revision f65069d of this guide.