Merge pull request #1179 from python-pillow/aclark-doc-nits

Aclark doc nits
This commit is contained in:
Alex Clark 2015-04-04 08:52:26 -04:00
commit 63eb28cb5b
10 changed files with 322 additions and 139 deletions

View File

@ -25,6 +25,7 @@ Released quarterly on the first day of January, April, July, October.
$ make sdistup
```
* [ ] Create and upload [binary distributions](#binary-distributions)
* [ ] Manually hide old versions on PyPI as needed, such that only the latest main release is visible when viewing https://pypi.python.org/pypi/Pillow
## Point Release

View File

@ -1 +0,0 @@
# Empty file, to make the directory available in the repository

View File

@ -4,7 +4,7 @@ About Pillow
Goals
-----
The fork authors' goal is to foster active development of PIL through:
The fork author's goal is to foster and support active development of PIL through:
- Continuous integration testing via `Travis CI`_
- Publicized development activity on `GitHub`_
@ -17,7 +17,7 @@ The fork authors' goal is to foster active development of PIL through:
License
-------
Like PIL, Pillow is licensed under the MIT-a-like `PIL Software License <http://www.pythonware.com/products/pil/license.htm>`_::
Like PIL, Pillow is licensed under the MIT-like open source `PIL Software License <http://www.pythonware.com/products/pil/license.htm>`_::
Software License
@ -35,10 +35,7 @@ Like PIL, Pillow is licensed under the MIT-a-like `PIL Software License <http://
Why a fork?
-----------
PIL is not setuptools compatible. Please see `this Image-SIG post`_ for a more
detailed explanation. Also, PIL's current bi-yearly (or greater) release
schedule is too infrequent to accommodate the large number and frequency of
issues reported.
PIL is not setuptools compatible. Please see `this Image-SIG post`_ for a more detailed explanation. Also, PIL's current bi-yearly (or greater) release schedule is too infrequent to accommodate the large number and frequency of issues reported.
.. _this Image-SIG post: https://mail.python.org/pipermail/image-sig/2010-August/006480.html
@ -50,14 +47,10 @@ What about PIL?
Prior to Pillow 2.0.0, very few image code changes were made. Pillow 2.0.0
added Python 3 support and includes many bug fixes from many contributors.
As more time passes since the last PIL release, the likelihood of a new PIL
release decreases. However, we've yet to hear an official "PIL is dead"
announcement. So if you still want to support PIL, please
`report issues here first`_, then
`open the corresponding Pillow tickets here`_.
As more time passes since the last PIL release, the likelihood of a new PIL release decreases. However, we've yet to hear an official "PIL is dead" announcement. So if you still want to support PIL, please `report issues here first`_, then `open corresponding Pillow tickets here`_.
.. _report issues here first: https://bitbucket.org/effbot/pil-2009-raclette/issues
.. _open the corresponding Pillow tickets here: https://github.com/python-pillow/Pillow/issues
.. _open corresponding Pillow tickets here: https://github.com/python-pillow/Pillow/issues
Please provide a link to the PIL ticket so we can track the issue(s) upstream.
Please provide a link to the first ticket so we can track the issue(s) upstream.

View File

@ -1,72 +1,288 @@
# -*- coding: utf-8 -*-
import PIL
#
# Pillow (PIL Fork) documentation build configuration file, created by
# sphinx-quickstart on Sat Apr 4 07:54:11 2015.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
### general configuration ###
import sys
import os
import shlex
needs_sphinx = '1.0'
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode',
'sphinx.ext.intersphinx']
intersphinx_mapping = {'http://docs.python.org/2/': None}
# -- General configuration ------------------------------------------------
source_suffix = '.rst'
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = []
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
project = u'Pillow (PIL fork)'
copyright = (u'1997-2011 by Secret Labs AB,'
u' 1995-2011 by Fredrik Lundh, 2010-2013 Alex Clark')
# General information about the project.
project = u'Pillow (PIL Fork)'
copyright = u'2015, Alex Clark'
author = u'Alex Clark'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
import PIL
version = PIL.PILLOW_VERSION
# The full version, including alpha/beta/rc tags.
release = version
release = PIL.PILLOW_VERSION
# currently excluding autodoc'd plugs
exclude_patterns = ['_build', 'plugins.rst']
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['_build']
# The reST default role (used for this markup: `text`) to use for all
# documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
### HTML output ###
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
#from better import better_theme_path
#html_theme_path = [better_theme_path]
#html_theme = 'better'
# If true, keep warnings as "system message" paragraphs in the built documents.
#keep_warnings = False
html_title = "Pillow v{release} (PIL fork)".format(release=release)
html_short_title = "Home"
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
html_theme_options = {}
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#html_extra_path = []
html_sidebars = {
'**': ['localtoc.html', 'sourcelink.html', 'sidebarhelp.html',
'searchbox.html'],
'index': ['globaltoc.html', 'sidebarhelp.html', 'searchbox.html'],
}
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
#html_search_language = 'en'
# A dictionary with options for the search language support, empty by default.
# Now only 'ja' uses this config value
#html_search_options = {'type': 'default'}
# The name of a javascript file (relative to the configuration directory) that
# implements a search results scorer. If empty, the default will be used.
#html_search_scorer = 'scorer.js'
# Output file base name for HTML help builder.
htmlhelp_basename = 'Pillowdoc'
htmlhelp_basename = 'PillowPILForkdoc'
# -- Options for LaTeX output ---------------------------------------------
### LaTeX output (RtD PDF output as well) ###
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
latex_elements = {}
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
# Latex figure (float) alignment
#'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
('index', 'Pillow.tex', u'Pillow (PIL fork) Documentation', u'Author',
'manual'),
(master_doc, 'PillowPILFork.tex', u'Pillow (PIL Fork) Documentation',
u'Alex Clark', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# skip_api_docs setting will skip PIL.rst if True. Used for working on the
# guides; makes livereload basically instantaneous.
def setup(app):
app.add_config_value('skip_api_docs', False, True)
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
skip_api_docs = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
if skip_api_docs:
exclude_patterns += ['PIL.rst']
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'pillowpilfork', u'Pillow (PIL Fork) Documentation',
[author], 1)
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'PillowPILFork', u'Pillow (PIL Fork) Documentation',
author, 'PillowPILFork', 'One line description of project.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
#texinfo_no_detailmenu = False

View File

@ -1,6 +1,8 @@
Appendices
==========
.. note:: Contributors please include appendices as needed or appropriate with your bug fixes, feature additions and tests.
.. toctree::
:maxdepth: 2

View File

@ -1,7 +1,7 @@
Pillow
======
Pillow is the 'friendly' PIL fork by Alex Clark and Contributors. PIL is the Python Imaging Library by Fredrik Lundh and Contributors.
Pillow is the "friendly PIL fork" by `Alex Clark and Contributors <https://github.com/python-pillow/Pillow/graphs/contributors>`_. PIL is the Python Imaging Library by Fredrik Lundh and Contributors.
.. image:: https://travis-ci.org/python-pillow/Pillow.svg?branch=master
:target: https://travis-ci.org/python-pillow/Pillow
@ -27,18 +27,16 @@ Pillow is the 'friendly' PIL fork by Alex Clark and Contributors. PIL is the Pyt
:target: https://landscape.io/github/python-pillow/Pillow/master
:alt: Code health
To install Pillow, please follow the :doc:`installation instructions <installation>`. To download source and/or contribute to development of Pillow please see: https://github.com/python-pillow/Pillow.
.. toctree::
:maxdepth: 2
installation
about
guides
reference/index.rst
handbook/appendices
releasenotes/index.rst
original-readme
about
pre-fork-readme
Indices and tables
==================

View File

@ -1,39 +1,32 @@
Installation
============
.. warning:: Pillow >= 2.1.0 no longer supports "import _imaging". Please use "from PIL.Image import core as _imaging" instead.
.. warning:: Pillow and PIL cannot co-exist in the same environment. Before installing Pillow, please uninstall PIL.
.. warning:: Pillow >= 1.0 no longer supports "import Image". Please use "from PIL import Image" instead.
.. warning:: PIL and Pillow currently cannot co-exist in the same environment.
If you want to use Pillow, please remove PIL first.
.. note:: Pillow >= 2.0.0 supports Python versions 2.6, 2.7, 3.2, 3.3, 3.4
.. warning:: Pillow >= 2.1.0 no longer supports "import _imaging". Please use "from PIL.Image import core as _imaging" instead.
.. note:: Pillow < 2.0.0 supports Python versions 2.4, 2.5, 2.6, 2.7.
Simple Installation
-------------------
.. note:: Pillow >= 2.0.0 supports Python versions 2.6, 2.7, 3.2, 3.3, 3.4
Basic Installation
------------------
.. note::
The following instructions will install Pillow with support for most formats.
See :ref:`external-libraries` for the features you would gain by installing
the external libraries first. This page probably also include specific
instructions for your platform.
The following instructions will install Pillow with support for most common image formats. See :ref:`external-libraries` for a full list of external libraries supported.
You can install Pillow with :command:`pip`::
Install Pillow with :command:`pip`::
$ pip install Pillow
Or :command:`easy_install` (for installing `Python Eggs
<http://peak.telecommunity.com/DevCenter/PythonEggs>`_, as :command:`pip` does
not support them)::
Or use :command:`easy_install` for installing `Python Eggs <http://peak.telecommunity.com/DevCenter/PythonEggs>`_ as :command:`pip` does not support them::
$ easy_install Pillow
Or download the `compressed archive from PyPI`_, extract it, and inside it
run::
Or download and extract the `compressed archive from PyPI`_ and inside it run::
$ python setup.py install
@ -46,7 +39,7 @@ External libraries
.. note::
You *do not* need to install all of the external libraries to use Pillow's basic features.
You **do not need to install all external libraries supported** to use Pillow's basic features.
Many of Pillow's features require external libraries:
@ -120,46 +113,6 @@ Sample Usage::
$ MAX_CONCURRENCY=1 python setup.py build_ext --enable-[feature] install
Linux Installation
------------------
.. note::
Fedora, Debian/Ubuntu, and ArchLinux include Pillow (instead of PIL) with
their distributions. Consider using those instead of installing manually.
**We do not provide binaries for Linux.** If you didn't build Python from
source, make sure you have Python's development libraries installed. In Debian
or Ubuntu::
$ sudo apt-get install python-dev python-setuptools
Or for Python 3::
$ sudo apt-get install python3-dev python3-setuptools
In Fedora, the command is::
$ sudo yum install python-devel
Prerequisites are installed on **Ubuntu 12.04 LTS** or **Raspian Wheezy
7.0** with::
$ sudo apt-get install libtiff4-dev libjpeg8-dev zlib1g-dev \
libfreetype6-dev liblcms2-dev libwebp-dev tcl8.5-dev tk8.5-dev python-tk
Prerequisites are installed on **Ubuntu 14.04 LTS** with::
$ sudo apt-get install libtiff5-dev libjpeg8-dev zlib1g-dev \
libfreetype6-dev liblcms2-dev libwebp-dev tcl8.6-dev tk8.6-dev python-tk
Prerequisites are installed on **Fedora 20** with::
$ sudo yum install libtiff-devel libjpeg-devel libzip-devel freetype-devel \
lcms2-devel libwebp-devel tcl-devel tk-devel
OS X Installation
-----------------
@ -213,7 +166,6 @@ FreeBSD Installation
.. Note:: Only FreeBSD 10 tested
Make sure you have Python's development libraries installed.::
$ sudo pkg install python2
@ -226,6 +178,45 @@ Prerequisites are installed on **FreeBSD 10** with::
$ sudo pkg install jpeg tiff webp lcms2 freetype2
Linux Installation
------------------
.. note::
Most major Linux distributions, including Fedora, Debian/Ubuntu and ArchLinux include Pillow in packages that previously contained PIL e.g. ``python-imaging``. Please consider using native operating system packages first to avoid installation problems and/or missing library support later.
**We do not provide binaries for Linux.** If you didn't build Python from
source, make sure you have Python's development libraries installed. In Debian
or Ubuntu::
$ sudo apt-get install python-dev python-setuptools
Or for Python 3::
$ sudo apt-get install python3-dev python3-setuptools
In Fedora, the command is::
$ sudo yum install python-devel
Prerequisites are installed on **Ubuntu 12.04 LTS** or **Raspian Wheezy
7.0** with::
$ sudo apt-get install libtiff4-dev libjpeg8-dev zlib1g-dev \
libfreetype6-dev liblcms2-dev libwebp-dev tcl8.5-dev tk8.5-dev python-tk
Prerequisites are installed on **Ubuntu 14.04 LTS** with::
$ sudo apt-get install libtiff5-dev libjpeg8-dev zlib1g-dev \
libfreetype6-dev liblcms2-dev libwebp-dev tcl8.6-dev tk8.6-dev python-tk
Prerequisites are installed on **Fedora 20** with::
$ sudo yum install libtiff-devel libjpeg-devel libzip-devel freetype-devel \
lcms2-devel libwebp-devel tcl-devel tk-devel
Platform support
@ -238,8 +229,7 @@ current versions of Linux, OS X, and Windows.
.. note::
Contributors please test on your platform, edit this document, and send a
pull request.
Contributors please test Pillow on your platform then update this document and send a pull request.
+----------------------------------+-------------+------------------------------+------------------------------+-----------------------+
|**Operating system** |**Supported**|**Tested Python versions** |**Tested Pillow versions** |**Tested processors** |

View File

@ -1,7 +1,7 @@
Original PIL README
===================
Pre-fork README
===============
What follows is the original PIL 1.1.7 README file contents.
What follows is the untouched, original pre-fork PIL 1.1.7 README file contents.
::

View File

@ -1,6 +1,8 @@
Release Notes
=============
.. note:: Contributors please include release notes as needed or appropriate with your bug fixes, feature additions and tests.
.. toctree::
:maxdepth: 2

View File

@ -1,19 +1 @@
sphinx-better-theme
## requirements for working on docs
#
## install pillow from master if you're into that, but RtD needs this
#pillow>=2.4.0
#
#Jinja2==2.7.1
#MarkupSafe==0.18
#Pygments==1.6
#Sphinx==1.1.3
#docopt==0.6.1
#docutils==0.11
#wsgiref==0.1.2
#sphinx-better-theme==0.1.5
#
## livereload not strictly necessary but really useful (make livehtml)
#tornado==3.1.1
#livereload==1.0.1
Sphinx