Supporting Python 3

Author: Lennart Regebro

CLA.txt

@@ -0,0 +1,82 @@
+Contributor License Agreement
+=============================
+
+You accept and agree to the following terms and conditions for Your present
+and future Contributions to the Work. Except for the license granted herein
+to Lennart Regebro, You reserve all right, title, and interest in and to Your
+Contributions.
+
+1. Definitions.
+
+   "You" (or "Your") shall mean the copyright owner or legal entity
+   authorized by the copyright owner that is making this Agreement with
+   Lennart Regebro. For legal entities, the entity making a Contribution and
+   all other entities that control, are controlled by, or are under common
+   control with that entity are considered to be a single Contributor. For
+   the purposes of this definition, "control" means (i) the power, direct or
+   indirect, to cause the direction or management of such entity, whether by
+   contract or otherwise, or (ii) ownership of fifty percent (50%) or more of
+   the outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "Contribution" shall mean any original work of authorship, including any
+   modifications or additions to an existing work, that is intentionally
+   submitted by You to Lennart Regebro for inclusion in, or documentation of,
+   the Work. For the purposes of this definition, "submitted" means any form
+   of electronic, verbal, or written communication sent to Lennart Regebro,
+   including but not limited to communication on electronic mailing lists,
+   source code control systems, and issue tracking systems for the purpose of
+   discussing and improving the Work, but excluding communication that is
+   conspicuously marked or otherwise designated in writing by You as "Not a
+   Contribution."
+   
+   "The Work" shall mean the book "Supporting Python 3" and it's code and
+   documentation.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+   Agreement, You hereby grant to Lennart Regebro a perpetual, worldwide,
+   non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+   reproduce, prepare derivative works of, publish, publicly display,
+   sublicense, and distribute Your Contributions and such derivative works.
+
+3. Grant of Patent License. Subject to the terms and conditions of this
+   Agreement, You hereby grant to Lennart Regebro and to recipients of
+   software distributed by Lennart Regebro a perpetual, worldwide,
+   non-exclusive, no-charge, royalty-free, irrevocable (except as stated in
+   this section) patent license to make, have made, use, offer to sell, sell,
+   import, and otherwise transfer the Work, where such license applies only
+   to those patent claims licensable by You that are necessarily infringed by
+   Your Contribution(s) alone or by combination of Your Contribution(s) with
+   the Work to which such Contribution(s) was submitted. If any entity
+   institutes patent litigation against You or any other entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that your Contribution,
+   or the Work to which you have contributed, constitutes direct or
+   contributory patent infringement, then any patent licenses granted to that
+   entity under this Agreement for that Contribution or Work shall terminate
+   as of the date such litigation is filed.
+
+4. You represent that you are legally entitled to grant the above license. If
+   your employer(s) has rights to intellectual property that you create that
+   includes your Contributions, you represent that you have received
+   permission to make Contributions on behalf of that employer, that your
+   employer has waived such rights for your Contributions to Lennart Regebro,
+   or that your employer has executed a separate Corporate CLA with Lennart
+   Regebro.
+
+5. You represent that each of Your Contributions is Your original creation
+   (see section 7 for submissions on behalf of others). You represent that
+   Your Contribution submissions include complete details of any third-party
+   license or other restriction (including, but not limited to, related
+   patents and trademarks) of which you are personally aware and which are
+   associated with any part of Your Contributions.
+
+6.  You are not expected to provide support for Your Contributions, except to
+   the extent You desire to provide support. You may provide support for
+   free, for a fee, or not at all. Unless required by applicable law or
+   agreed to in writing, You provide Your Contributions on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied,
+   including, without limitation, any warranties or conditions of TITLE, NON-
+   INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
+
+7. You agree to notify Lennart Regebro of any facts or circumstances of
+   which you become aware that would make these representations
+   inaccurate in any respect.

INSTALL.txt

@@ -0,0 +1,49 @@
+Installation
+============
+
+You need a Python with Sphinx installed. It's tested with Python 3.4, but
+any Python with Sphinx is likely to work.
+
+To run make spell you need aspell and american english dictionaries.
+
+* Debian-based: ``apt-get install aspell-en``
+* Red Hats: ``yum install aspell-en``
+
+To make pdf's you need Texlive 2013:
+
+* Debian-based: ``apt-get install texlive-full``
+* Red Hats: ``yum install texlive*``
+* Other systems: http://www.tug.org/texlive/quickinstall.html
+
+You also need the following fonts:
+
+* Flux Bold (FLUXB___.ttf)
+  This is a commercial font, so you need to buy it if you want to generate PDF's.
+* DejaVu Sans Mono
+  It's included in many Linux distro's by default.
+* TeX Gyre Schola
+  http://www.gust.org.pl/projects/e-foundry/tex-gyre/schola
+  Installable as ``texlive-tex-gyre`` on RPM based linuces and
+  ``fonts-texgyre`` on DEB based linuces.
+
+
+Testing setup
+=============
+
+(This is all stupid and needs to change. We should probably use Spiny.
+We can't use Tox, because it doesn't support old Python versions.)
+
+Python 2.3, 2.4 and 2.5 must be installed in ``/opt/python23`` etc (or paths
+changed in runtest.sh)
+
+Python 2.6, 2.7, 3.1, 3.1 and 3.3 must be installed in ``./python26``,
+``./python27``, etc (virtualenvs are fine).
+
+In Python 2.6 and above also do this::
+
+    pip install zope.interface setuptools==11.2
+
+Run the tests with ``make test``. Some tests may fail on the first time, with
+warnings like ``warning: no previously-included files matching '*.pyc' found
+anywhere in distribution``. Re-running them solves that.
+

Makefile

@@ -0,0 +1,96 @@
+# Makefile for Sphinx documentation
+#
+
+export PYTHONPATH = $(shell echo "$$PYTHONPATH"):.
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = ./bin/sphinx-build
+PAPER         =
+BUILDDIR      = build
+
+# Internal variables.
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(SPHINXOPTS) source
+
+LATEXPATH = $${PATH}
+LATEXEXE = xelatex
+LATEXOPTS =
+
+OUTPUTNAME=SupportingPython3
+
+SPELL = aspell -l en_US
+
+.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html      to make standalone HTML files"
+	@echo "  dirhtml   to make HTML files named index.html in directories"
+	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  pdf       to make a PDF"
+	@echo "  epub      to make an ePUB book"
+	@echo "  changes   to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck to check all external links for integrity"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub pages are in $(BUILDDIR)/epub."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
+	      "run these through (pdf)latex."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+pdf: latex
+	# Copy in some custom files
+	cp source/_templates/sphinxcustom.cls $(BUILDDIR)/latex/sphinxcustom.cls
+	cp source/_templates/sphinx.sty $(BUILDDIR)/latex/sphinx.sty
+	cp source/_static/by-nc-sa.pdf $(BUILDDIR)/latex/by-nc-sa.pdf
+	# Run LaTeX three times, the first time generates the text:
+	cd $(BUILDDIR)/latex; PATH=$(LATEXPATH) $(LATEXEXE) $(LATEXOPTS) $(OUTPUTNAME).tex
+	# Create the indexes
+	-cd $(BUILDDIR)/latex; PATH=$(LATEXPATH) makeindex -s python.ist $(OUTPUTNAME).idx
+	# Re run LaTex with indexes. Now we get a content listing and an index.
+	cd $(BUILDDIR)/latex; PATH=$(LATEXPATH) $(LATEXEXE) $(LATEXOPTS) $(OUTPUTNAME).tex
+	# Recreate the index since all the page numbers changed when the content listing appeared.
+	-cd $(BUILDDIR)/latex; PATH=$(LATEXPATH) makeindex -s python.ist $(OUTPUTNAME).idx
+	# And run LaTex again, this time with correct page numbers
+	cd $(BUILDDIR)/latex; PATH=$(LATEXPATH) $(LATEXEXE) $(LATEXOPTS) $(OUTPUTNAME).tex
+
+spell:
+	for f in source/*.rst; do $(SPELL) -c $$f; done
+
+stats:
+	wc source/*.rst
+
+test:
+	./runtests.sh
+
+check: spell test stats

README.txt

@@ -0,0 +1,77 @@
+Supporting Python 3
+===================
+
+This is a free book about how to make your code support Python 3.
+
+It costs nothing, and you can both publish it and contribute to it!
+
+
+Reading this book
+-----------------
+
+Supporting Python 3 is available for free on http://python3porting.com/ . You
+can also download a PDF version from https://gumroad.com/l/python3 for any
+price you like, and you can buy a paper version from
+https://www.createspace.com/4312357 for $4.45, which is the printing cost of
+the book, and hence as close to free as you can possibly come.
+
+As of today, the name of the book in all these places are "Porting to Python
+3", which is the old name of the book before I made it into a community
+effort. This will change sometime during 2015, and the above links will also
+change as a result.
+
+
+Contributing to this book
+-------------------------
+
+To contribute to this book, fork it on
+`GitHub https://github.com/regebro/supporting-python-3`_.
+
+Follow the instructions in INSTALL.txt on how to install it, and
+make the changes you like, and create a pull request.
+
+It's probably a good idea to talk to Lennart Regebro before making major
+changes or additions.
+
+
+License
+-------
+
+This book is (c) Lennart Regebro 2011-2015, and is licensed under a Creative
+Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License.
+
+See http://creativecommons.org/licenses/by-nc-sa/3.0/
+
+This means you can publish this book or parts of it, but not in such a way
+that you make money from it. Should you want to use this book in a commercial
+setting, please contact Lennart Regebro, [email protected].
+
+The book in it's current form uses Flux Bold, which is a commercial font.
+If you want to publish this book in any form, you need either to replace
+this font, or buy a license for the usage that you intend.
+
+Generating the PDFs
+-------------------
+
+Making a PDF is not just a matter of doing ``make pdf``. Doing so will indeed
+create a PDF, but you need to create four PDF's when releasing the book.
+
+You need::
+
+* A print PDF, 6" x 9", black only.
+* A screen PDF, 8.27" x 11", with syntax highlighting.
+* A tablet PDF, 7" x 9", with syntax highlighting.
+* A phone PDF, 4.8" x 7.2", with syntax highlighting.
+
+You do this by changing the conf.py. For the print PDF, the ``pygments_style``
+should be ``"none"`` otherwise it should be ``"sphinx"``.
+
+To select the paper size, change the used variable in ``print_latex_elements``
+between ``print_form``, ``screen_form``, ``tablets_form`` or ``phone_form``.
+
+You don't need to do anything more for the Print PDF, it's done, but the
+other PDF's should have the front and back covers merged. This can be done
+with tools like pdfunite::
+
+    $ pdfunite covers/PhoneFront.pdf build/latex/SupportingPython3.pdf \
+        covers/PhoneBack.pdf SupportingPython3-phone-1.0-dev.pdf

UTF-8.txt

@@ -0,0 +1 @@
+It wörks

covers/802764156_859a8f6969_o.jpg

@@ -0,0 +1,83 @@
+How to make covers
+==================
+
+The cover is in the Covers.xcf file. That's a GIMP file, so you need to use
+GIMP to open it for editing and PDF generation. And you need to create a lot
+of PDF's. You will also need GhostScript installed.
+
+The Covers.xcf is designed for use with Createspace self publishing.
+For more information on the PDF requirements, check with createspace.
+
+The Spine of the book is the number of interior pages * 0.002252 inches.
+If a significant amount of pages is added to the book, you may need to
+adjust the design.
+
+The two top layers are:
+
+* BookCover6X9_BW_140. This is an import of the Createspace cover template.
+  It's for 140 pages, and the book is currently 151, but that's not enough
+  to create a problem.
+
+* Preview Mask. This is a gray mask that will allow you to see approximately
+  the area that the printed cover will be.
+
+Both these layers must be invisible when printing the cover.
+
+
+Custom paper sizes
+------------------
+
+The PDF's come in three formats: Print, Phone, Tablet and Screen. OK, fine,
+phones and tablets are also screens, but they are also computers, and "PC"
+kinda implies it's not a Mac, so I choose "screen" as a name.
+
+To create the cover PDFs them you need to create several custom paper sizes.
+There should be creates with 0 page margins, and the following sizes
+(width x height):
+
+* Print size: 17" x 11"
+* Phone size: 4.8" x 7.2"
+* Tablet size: 6" x 9"
+* Screen size: 7.32" x 11"
+  (This fits both in A4 and Letter and hence you can also print it.)
+
+
+The print cover PDF
+-------------------
+
+To create the cover for printing, select the custom paper size that is 17" wide
+by 11" high. Go to the Image Settings tab in the print dialog, select "Ignore
+page margins" and then scale the image to as big as possible.
+
+Print to a file in portrait mode. Yes, that portrait mode will be wider than
+high, but that's not a problem. The default output for printing is typically a
+file called ``output.pdf`` in your home directory.
+
+The resulting PDF will be sent to the printing company to make the cover, and
+the PDF created by Sphinx is the inside pages. The printing companies I have
+used for the big conference print runs have both accepted this PDF, and it's
+designed for use with Createspace. Other online self-publishing companies may
+have other requirements.
+
+
+The PDF covers
+--------------
+
+The PDF issues should also have covers, but unlike the print cover they
+should contain only the printed area. Therefore you must crop the image
+before printing. Turn on the preview mask, make sure that Snap to guides
+is enabled and crop away the gray area and the spine. The resulting image
+should be approximately 6" x 9".
+
+This image you then print to the Phone, Tablet and Screen papers, again
+while ignoring page margins and scaling the image to be as big as possible.
+The resulting images will be too heavy, with front covers being around 6MB.
+
+Therefore you need to optimize each PDF with Ghostscript. The command to
+optimize the front PDF for the Phone size would be this::
+
+  gs -dNOPAUSE -dBATCH -sDEVICE=pdfwrite -dCompatibilityLevel=1.4  -sOutputFile=PhoneFront.pdf ~/output.pdf
+
+Repeat for each of the sizes, and then do the same for the back cover.
+
+Done!