Port PIL Handbook tutorial and appendices

[irskep]

Click here to see the results

I ported sections 1 (tutorials) and 4 (appendices) from the PIL Handbook.

I also switched the docs to use a Sphinx theme I'm working on. Of course I can snip that commit out if you don't like it, but I think you'll like it.

The API reference is now split into "PIL" and "plugins." The latter is larger and less important, so I made it easier to ignore while still just as accessible.

Additionally, I added a make livehtml target so you don't have to build/refresh manually while editing.

I skipped the reference and tool sections for now. I (or someone else) can come back and do them later. I just got tired of translating HTML to Sphinx by hand.

Let me know if you want anything changed.

[irskep]

Oh, I'm still getting some ImportErrors building the docs, not sure if they're important. One about PyQt4 (I probably just didn't install it), and one about _webp, which looks like an extension that isn't getting compiled.

[irskep]

As a side note, we really can't have every module on the same page as a long-term API documentation strategy. It's too hard to use, should be split up later.

[wiredfool]

@irskep Thanks for your work on this. Looks good from a quick skim. I can see areas where pillow has diverged from what's documented, so that's going to be another far less mechanical project. E.g tiff compression, webp in general.

_webp requires libwebp to be installed, it's a relatively new format added in Pillow, not in the original PIL project.

[irskep]

If you leave comments on the diff, I can mark them with an out-of-date warning.

[irskep]

I'd also be happy to add Python version compatibility notes and installation procedures on the main page.

[irskep]

I should also make it clear that I'll probably be less than useful with proofreading specific technical features. I've only ever used PIL casually and just got tired of reading the old PIL docs when using pillow. Plus I like excuses to promote my Sphinx theme. Hence this pull request.

So I won't be able to rewrite the out-of-date sections accurately, just mark them as such and link to the changelog.

Oh, I suppose I should also put the release notes in the docs.

[wiredfool]

Understood. Those two notes are just the ones that jumped out directly, there's been other bits to be sure. Once we've got this pulled in and converted in its current state of matching PIL 1.1.5 (or so), we (the people who've been hacking and not documenting) are going to need to do some serious updates. At least it's already importing Image from PIL.

[irskep]

OOD, supported since 1.1.7

[irskep]

Yeah, I changed that much. :-)

[irskep]

"Writing your own decoder" raw modes table is missing "+ Added limited support for I;16L mode (explicit little endian)." Not sure how to write the description.

[irskep]

(We can turn some of these comments into open issues rather than trying to fix them all now)

[irskep]

Looks like WMF is supported better than these docs claim. I'm not sure to what degree.

[wiredfool]

Yeah. Didn't mean to derail with details.

Is there any way that the PIL Package docs can start with Image, or at least highlight it? That's the one that 99% of people are going to want to start with. I'm not even sure that the Plugin stuff is worth having there, given that it's basically a list of internal functions with no documentation.

[wiredfool]

There are a lot more modes than the documentation lets on. Some more useful than others, many mainly useful as conversions from numpy arrays. I wouldn't worry about them now.

[irskep]

Sure, that's no problem. It's good to pick things out here and triage what to do now vs later.

The plugin stuff can matter a lot if you need to do things like set PDF resolution on save, or do JPEG-specific things. That stuff isn't documented at all, but it could be. (These are things I found in the changelog but not in the docs.) So we should probably leave it in. The plugins are all the file format-specific stuff.

[irskep]

Is the new TIFF stuff dependent on libtiff being installed separately from PIL or does it get pulled in on install?

[wiredfool]

The libtiff stuff relies on libtiff+headers being installed. (as is the case with any of the other external libraries. they're technically optional, but some of them are more optional than others).

I agree that the plugins can be useful. However, the current documentation, autogenerated as it is, is not.

[irskep]

Okay, I'll take it out of the table of contents and prevent it from being built. Will leave the file intact for the future.

[irskep]

Updated TIFF description

[wiredfool]

Cool. Off for now, will be back in the morning.

[irskep]

I'll save porting the README material for a later pull request.

[irskep]

Fixed print function stuff in tutorial. Checking out for the night. I recommend we limit further changes to fixing outright errors and save real improvements for separate (and smaller!) branches.

The original link to the preview should stay up to date, I've got it tracking my branch.

[aclark4life]

Very nice, thanks! Should I merge then @irskep @wiredfool ?

[wiredfool]

I'd say merge.

[aclark4life]

Thanks all

[irskep]

It looks like RtD didn't update. Does it track a release branch rather than master? Does the Github hook still need to be enabled?

[aclark4life]

Exception occurred:
  File "/var/build/user_builds/pillow/checkouts/latest/docs/conf.py", line 95, in <module>
    from better import better_theme_path
ImportError: No module named better
The full traceback has been saved in /tmp/sphinx-err-VhyWDV.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
Either send bugs to the mailing list at <http://groups.google.com/group/sphinx-dev/>,
or report them in the tracker at <http://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!

[irskep]

2 ways to handle this:

1. Make me an admin of the project on RtD so I can fix it, my username is stevejohnson
2. Do these things in the admin panel:
   • Enable virtualenv
   • Point the 'requirements file' field at docs/requirements.txt
   • Point the 'Sphinx conf file' field at docs/conf.py

[aclark4life]

Done (#1)

[irskep]

Fixed.

[aclark4life]

\o/ Thanks.