diff --git a/docs/source/detailed_installation.rst b/docs/source/detailed_installation.rst new file mode 100644 index 0000000..1771722 --- /dev/null +++ b/docs/source/detailed_installation.rst @@ -0,0 +1,110 @@ +----------------------------------------------------- +Detailed Instructions for Package Management, Testing +----------------------------------------------------- + +You only need to read this page if you want detailed +platform-specific instructions on running as many tests as possible or wish to +use your system's package manager to install as many required +packages/RPMs/ports/whatever without going through pip. Otherwise go on to +the next page. + +'''''''' +Platform +'''''''' + +Mac OS X +-------- +All the necessary packages are available to use glymur with Python 3.3 via +MacPorts. A minimal set of ports includes + + * python33 + * py33-numpy + * py33-distribute + +To run all the testing, one of the following combinations of ports must +additionally be installed: + + * py33-scikit-image and either py33-Pillow or freeimage + * py33-matplotlib and py33-Pillow + +Linux +----- + +Fedora 18 +''''''''' +Fedora 18 ships with Python 3.3, so all the necessary RPMs are available to +meet the minimal set of requirements. + + * python3 + * python3-numpy + * python3-setuptools + * python3-matplotlib (for running tests) + * python3-matplotlib-tk (or whichever matplotlib backend you prefer) + +A few tests still will not run, however, unless one of the following +combinations of RPMs / Python packages is installed. + + * scikit-image and either Pillow or freeimage + * matplotlib and Pillow + +The 2nd route is probably the easiest, so go ahead and install Pillow +via pip since Pillow is not yet available in Fedora 18 default +repositories:: + + $ yum install python3-devel # pip needs this in order to compile Pillow + $ yum install python3-pip + $ pip-python3 install Pillow --user + $ export PYTHONPATH=$HOME/.local/lib/python3.3/site-packages:$PYTHONPATH + +Fedora 17 +''''''''' +Fedora 17 ships with Python 3.2 and 2.7, so these steps detail working with +2.7. + +Required RPMs include:: + + * python + * python-mock + * python-pip + * python-setuptools + * numpy + +In addition, you must install contextlib2 via pip. + +A few tests still will not run, however, unless one of the following +combinations of RPMs / Python packages is installed. + + * scikit-image and either Pillow or freeimage + * matplotlib and Pillow + +scikit-image is not available in the Fedora 17 default repositories, but +it may be installed via pip:: + + $ yum install Cython # pip needs this in order to compile scikit-image + $ yum install python-devel # pip needs this in order to compile scikit-image + $ yum install freeimage # scikit-image uses this as a backend + $ yum install scipy # needed by scikit-image + $ pip-python install scikit-image --user + $ pip-python install contextlib2 --user + $ export PYTHONPATH=$HOME/.local/lib/python2.7/site-packages:$PYTHONPATH + +Windows +------- +Not currently supported. + +''''''' +Testing +''''''' + +If you wish to run the tests (strongly suggested :-), try the following + + $ cd /to/where/you/unpacked/glymur + $ python -m unittest discover + +Quite a few tests are currently skipped. These include tests whose +OpenJPEG counterparts are already failing, and others which do pass but +still produce heaps of output on stderr. Rather than let this swamp +the signal (that most of the tests are actually passing), they've been +filtered out for now. There are also more skipped tests on Python 2.7 +than on Python 3.3. The important part is whether or not any test +errors are reported at the end. diff --git a/docs/source/index.rst b/docs/source/index.rst index bcc2d75..8536be8 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -13,6 +13,7 @@ Contents: :maxdepth: 2 introduction + detailed_installation how_do_i roadmap api diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst index 3b8ba4e..d21d7eb 100644 --- a/docs/source/introduction.rst +++ b/docs/source/introduction.rst @@ -19,13 +19,10 @@ some very limited support for reading JPX metadata. For instance, **asoc** and **labl** boxes are recognized, so GMLJP2 metadata can be retrieved from such JPX files. -'''''''''''' -Installation -'''''''''''' -glymur works on Python 2.7 and 3.3. Python 3.3 is strongly recommended. +Glymur works on Python 2.7 and 3.3. Python 3.3 is strongly recommended. -OpenJPEG -======== +OpenJPEG Installation +===================== OpenJPEG must be built as a shared library. In addition, you currently must compile OpenJPEG from the developmental source that you can retrieve via subversion. As of this time of writing, svn @@ -55,8 +52,8 @@ the openjp2 library. You may create the configuration file as follows:: That assumes, of course, that you've installed OpenJPEG into /opt/openjp2-svn. You may also replace **$HOME/.config** with **$XDG_CONFIG_HOME**. -Glymur -====== +Glymur Installation +=================== You can retrieve the source for Glymur from either of * https://pypi.python.org/pypi/Glymur/ (stable releases) @@ -73,105 +70,3 @@ to take advantage of it. For example, if you install with pip's $ export PYTHONPATH=$HOME/.local/lib/python3.3/site-packages $ export PATH=$HOME/.local/bin:$PATH - -You only need to read further on this page if you want detailed -platform-specific instructions on running as many tests as possible or wish to -use your system's package manager to install as many required -packages/RPMs/ports/whatever without going through pip. - -Mac OS X --------- -All the necessary packages are available to use glymur with Python 3.3 via -MacPorts. A minimal set of ports includes - - * python33 - * py33-numpy - * py33-distribute - -To run all the testing, one of the following combinations of ports must -additionally be installed: - - * py33-scikit-image and either py33-Pillow or freeimage - * py33-matplotlib and py33-Pillow - -Linux ------ - -Fedora 18 -''''''''' -Fedora 18 ships with Python 3.3, so all the necessary RPMs are available to -meet the minimal set of requirements. - - * python3 - * python3-numpy - * python3-setuptools - * python3-matplotlib (for running tests) - * python3-matplotlib-tk (or whichever matplotlib backend you prefer) - -A few tests still will not run, however, unless one of the following -combinations of RPMs / Python packages is installed. - - * scikit-image and either Pillow or freeimage - * matplotlib and Pillow - -The 2nd route is probably the easiest, so go ahead and install Pillow -via pip since Pillow is not yet available in Fedora 18 default -repositories:: - - $ yum install python3-devel # pip needs this in order to compile Pillow - $ yum install python3-pip - $ pip-python3 install Pillow --user - $ export PYTHONPATH=$HOME/.local/lib/python3.3/site-packages:$PYTHONPATH - -Fedora 17 -''''''''' -Fedora 17 ships with Python 3.2 and 2.7, so these steps detail working with -2.7. - -Required RPMs include:: - - * python - * python-mock - * python-pip - * python-setuptools - * numpy - -In addition, you must install contextlib2 via pip. - -A few tests still will not run, however, unless one of the following -combinations of RPMs / Python packages is installed. - - * scikit-image and either Pillow or freeimage - * matplotlib and Pillow - -scikit-image is not available in the Fedora 17 default repositories, but -it may be installed via pip:: - - $ yum install Cython # pip needs this in order to compile scikit-image - $ yum install python-devel # pip needs this in order to compile scikit-image - $ yum install freeimage # scikit-image uses this as a backend - $ yum install scipy # needed by scikit-image - $ pip-python install scikit-image --user - $ pip-python install contextlib2 --user - $ export PYTHONPATH=$HOME/.local/lib/python2.7/site-packages:$PYTHONPATH - -Windows -------- -Not currently supported. - -''''''' -Testing -''''''' - -The test suite may then be run with:: - - $ cd /to/where/you/unpacked/glymur - $ python -m unittest discover - -Quite a few tests are currently skipped. These include tests whose -OpenJPEG counterparts are already failing, and others which do pass but -still produce heaps of output on stderr. Rather than let this swamp -the signal (that most of the tests are actually passing), they've been -filtered out for now. There are also more skipped tests on Python 2.7 -than on Python 3.3. The important part is whether or not any test -errors are reported at the end.