Merge pull request #798 from wiredfool/doc_cleanup

Doc cleanup

Makefile

@@ -1,4 +1,16 @@
+.PHONY: pre clean install test inplace coverage test-dep help docs livedocs
 
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  clean		remove build products"
+	@echo "  install	make and install"
+	@echo "  test		run tests on installed pillow"
+	@echo "  inplace	make inplace extension" 
+	@echo "  coverage	run coverage test (in progress)"
+	@echo "  docs		make html docs"
+	@echo "  docserver	run an http server on the docs directory"
+	@echo "  test-dep	install coveraget and test dependencies"
 
 pre:
 	virtualenv .
@@ -18,12 +30,11 @@ clean:
 	rm -r build || true
 	find . -name __pycache__ | xargs rm -r || true
 
-
 install:
 	python setup.py install
 	python selftest.py --installed
 
-test: install
+test:
 	python test-installed.py
 
 inplace: clean
@@ -42,3 +53,9 @@ coverage:
 
 test-dep:
 	pip install coveralls nose nose-cov pep8 pyflakes
+
+docs:
+	$(MAKE) -C docs html
+
+docserver:
+	cd docs/_build/html && python -mSimpleHTTPServer 2> /dev/null&

PIL/ImageCms.py

@@ -1,19 +1,19 @@
-"""
-The Python Imaging Library.
-$Id$
+## The Python Imaging Library.
+## $Id$
 
-Optional color managment support, based on Kevin Cazabon's PyCMS
-library.
+## Optional color managment support, based on Kevin Cazabon's PyCMS
+## library.
 
-History:
-2009-03-08 fl   Added to PIL.
+## History:
 
-Copyright (C) 2002-2003 Kevin Cazabon
-Copyright (c) 2009 by Fredrik Lundh
+## 2009-03-08 fl   Added to PIL.
 
-See the README file for information on usage and redistribution.  See
-below for the original description.
-"""
+## Copyright (C) 2002-2003 Kevin Cazabon
+## Copyright (c) 2009 by Fredrik Lundh
+## Copyright (c) 2013 by Eric Soroos
+
+## See the README file for information on usage and redistribution.  See
+## below for the original description.
 
 from __future__ import print_function
 
@@ -637,7 +637,7 @@ def getProfileName(profile):
 
     (pyCMS) Gets the internal product name for the given profile.
 
-     If profile isn't a valid CmsProfile object or filename to a profile,
+    If profile isn't a valid CmsProfile object or filename to a profile,
     a PyCMSError is raised If an error occurs while trying to obtain the
     name tag, a PyCMSError is raised.
 
@@ -876,7 +876,7 @@ def isIntentSupported(profile, intent, direction):
     input/output/proof profile as you desire.
 
     Some profiles are created specifically for one "direction", can cannot
-     be used for others.  Some profiles can only be used for certain
+    be used for others.  Some profiles can only be used for certain
     rendering intents... so it's best to either verify this before trying
     to create a transform with them (using this function), or catch the
     potential PyCMSError that will occur if they don't support the modes

PIL/OleFileIO.py

@@ -15,8 +15,11 @@ Improved version of the OleFileIO module from PIL library v1.1.6
 See: http://www.pythonware.com/products/pil/index.htm
 
 The Python Imaging Library (PIL) is
+
     Copyright (c) 1997-2005 by Secret Labs AB
+    
     Copyright (c) 1995-2005 by Fredrik Lundh
+
 OleFileIO_PL changes are Copyright (c) 2005-2014 by Philippe Lagadec
 
 See source code and LICENSE.txt for information on usage and redistribution.
@@ -1701,10 +1704,12 @@ class OleFileIO:
         Open a stream as a read-only file object (BytesIO).
 
         filename: path of stream in storage tree (except root entry), either:
+        
             - a string using Unix path syntax, for example:
               'storage_1/storage_1.2/stream'
             - a list of storage filenames, path to the desired stream/storage.
               Example: ['storage_1', 'storage_1.2', 'stream']
+              
         return: file object (read-only)
         raise IOError if filename not found, or if this is not a stream.
         """
@@ -1722,6 +1727,7 @@ class OleFileIO:
 
         filename: path of stream in storage tree. (see openstream for syntax)
         return: False if object does not exist, its entry type (>0) otherwise:
+        
             - STGTY_STREAM: a stream
             - STGTY_STORAGE: a storage
             - STGTY_ROOT: the root entry
@@ -1812,7 +1818,7 @@ class OleFileIO:
         filename: path of stream in storage tree (see openstream for syntax)
         convert_time: bool, if True timestamps will be converted to Python datetime
         no_conversion: None or list of int, timestamps not to be converted
-                       (for example total editing time is not a real timestamp)
+        (for example total editing time is not a real timestamp)
         return: a dictionary of values indexed by id (integer)
         """
         # make sure no_conversion is a list, just to simplify code below:

PIL/PSDraw.py

@@ -73,9 +73,8 @@ class PSDraw:
 
     def setink(self, ink):
         """
-        .. warning::
+        .. warning:: This has been in the PIL API for ages but was never implemented.
 
-            This has been in the PIL API for ages but was never implemented.
         """
         print("*** NOT YET IMPLEMENTED ***")
 

_imagingcms.c

@@ -6,6 +6,8 @@
  * http://www.cazabon.com
  * Adapted/reworked for PIL by Fredrik Lundh
  * Copyright (c) 2009 Fredrik Lundh
+ * Updated to LCMS2
+ * Copyright (c) 2013 Eric Soroos
  *
  * pyCMS home page:  http://www.cazabon.com/pyCMS
  * littleCMS home page:  http://www.littlecms.com

docs/PIL.rst

@@ -52,15 +52,8 @@ can be found here.
     :undoc-members:
     :show-inheritance:
 
-:mod:`ImageCms` Module
-----------------------
-
-.. automodule:: PIL.ImageCms
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 .. intentionally skipped documenting this because it's not documented anywhere
+
 :mod:`ImageDraw2` Module
 ------------------------
 
@@ -70,6 +63,7 @@ can be found here.
     :show-inheritance:
 
 .. intentionally skipped documenting this because it's deprecated
+
 :mod:`ImageFileIO` Module
 -------------------------
 

docs/reference/Image.rst

@@ -49,7 +49,10 @@ Functions
 
 .. autofunction:: open
 
-    .. warning:: > To protect against potential DOS attacks caused by "`decompression bombs<https://en.wikipedia.org/wiki/Zip_bomb>`_" (i.e. malicious files which decompress into a huge amount of data and are designed to crash or cause disruption by using up a lot of memory), Pillow will issue a `DecompressionBombWarning` if the image is over a certain limit. If desired, the warning can be turned into an error with `warnings.simplefilter('error', Image.DecompressionBombWarning)` or suppressed entirely with `warnings.simplefilter('ignore', Image.DecompressionBombWarning)`. See also `the logging documentation<https://docs.python.org/2/library/logging.html?highlight=logging#integration-with-the-warnings-module>`_ to have warnings output to the logging facility instead of stderr.
+    .. warning:: To protect against potential DOS attacks caused by "`decompression bombs`_" (i.e. malicious files which decompress into a huge amount of data and are designed to crash or cause disruption by using up a lot of memory), Pillow will issue a `DecompressionBombWarning` if the image is over a certain limit. If desired, the warning can be turned into an error with `warnings.simplefilter('error', Image.DecompressionBombWarning)` or suppressed entirely with `warnings.simplefilter('ignore', Image.DecompressionBombWarning)`. See also `the logging documentation`_ to have warnings output to the logging facility instead of stderr.
+
+	.. _decompression bombs: https://en.wikipedia.org/wiki/Zip_bomb
+	.. _the logging documentation: https://docs.python.org/2/library/logging.html?highlight=logging#integration-with-the-warnings-module
 
 Image processing
 ^^^^^^^^^^^^^^^^

docs/reference/ImageCms.rst

@@ -0,0 +1,13 @@
+.. py:module:: PIL.ImageCms
+.. py:currentmodule:: PIL.ImageCms
+
+:py:mod:`ImageCms` Module
+=========================
+
+The :py:mod:`ImageCms` module provides color profile management
+support using the LittleCMS2 color management engine, based on Kevin
+Cazabon's PyCMS library.
+
+.. automodule:: PIL.ImageCms
+    :members:
+    :noindex:

docs/reference/index.rst

@@ -8,6 +8,7 @@ Reference
    Image
    ImageChops
    ImageColor
+   ImageCms
    ImageDraw
    ImageEnhance
    ImageFile