Skip to content

Commit 20452db

Browse files
mahmoudhossammahmoudhossam
committed
Merge upstream.
2 parents 555311d + c1a57ae commit 20452db

30 files changed

+1642
-237
lines changed

‎docs/conf.py

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@
2525

2626
# Add any Sphinx extension module names here, as strings. They can be extensions
2727
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
28-
extensions = ['sphinx.ext.ifconfig', 'sphinx.ext.todo']
28+
extensions = ['sphinx.ext.ifconfig', 'sphinx.ext.todo', 'sphinx.ext.intersphinx']
2929

3030
# Add any paths that contain templates here, relative to this directory.
3131
templates_path = ['_templates']
@@ -260,3 +260,7 @@
260260
#epub_tocdup = True
261261

262262
todo_include_todos = True
263+
264+
intersphinx_mapping = {
265+
'python': ('http://docs.python.org/', None),
266+
}

‎docs/contents.rst.inc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,8 @@ different scenarios.
5353
scenarios/ci
5454
scenarios/speed
5555
scenarios/scientific
56+
scenarios/imaging
57+
scenarios/xml
5658

5759

5860
Shipping Great Code

‎docs/dev/env.rst

Lines changed: 75 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,12 @@ however, using a more powerful editor may make your life a bit easier.
1212
VIM
1313
---
1414

15-
16-
There exist a couple of plugins and settings for the VIM editor to aid python
17-
development. If you only develop in Python, a good start is to set the default
18-
settings for indentation and linewrapping to values compliant with PEP8::
15+
Vim is a text editor which uses keyboard shortcuts for editing instead of menus
16+
or icons. There exist a couple of plugins and settings for the VIM editor to
17+
aid python development. If you only develop in Python, a good start is to set
18+
the default settings for indentation and linewrapping to values compliant with
19+
`PEP 8 <http://www.python.org/dev/peps/pep-0008/>`_. In your home directory,
20+
open a file called `.vimrc` and add the following lines: ::
1921

2022
set textwidth=79
2123
set shiftwidth=4
@@ -24,25 +26,26 @@ settings for indentation and linewrapping to values compliant with PEP8::
2426
set softtabstop=4
2527
set shiftround
2628

27-
With these settings newlines are inserted after 79 characters and indentation
29+
With these settings, newlines are inserted after 79 characters and indentation
2830
is set to 4 spaces per tab. If you also use VIM for other languages, there is a
2931
handy plugin at indent_, which handles indentation settings for python source
3032
files.
31-
Additionally there is also a handy syntax plugin at syntax_ featuring some
32-
improvements over the syntax file included in VIM 6.1.
33+
34+
There is also a handy syntax plugin at syntax_ featuring some improvements over
35+
the syntax file included in VIM 6.1.
3336

3437
These plugins supply you with a basic environment for developing in Python.
35-
However in order to improve the programming flow we also want to continually
36-
check for PEP8 compliance and check syntax. Luckily there exist PEP8_ and
37-
Pyflakes_ to do this for you. If your VIM is compiled with `+python` you can
38-
also utilize some very handy plugins to do these checks from within the editor.
39-
For PEP8 checking install vim-pep8_. Now you can map the vim function
40-
`Pep8()` to any hotkey or action you want. Similarly for pyflakes you can
41-
install vim-pyflakes_. Now you can map `Pyflakes()` like the PEP8 function and
42-
have it called quickly. Both plugins will display errors in a quickfix list and
43-
provide an easy way to jump to the corresponding line. A very handy setting is
44-
calling these functions whenever a buffer is saved. In order to do this, enter
45-
the following lines into your vimrc::
38+
To get the most out of Vim, you should continually check your code for syntax
39+
errors and PEP8 compliance. Luckily PEP8_ and Pyflakes_ will do this for you.
40+
If your VIM is compiled with `+python` you can also utilize some very handy
41+
plugins to do these checks from within the editor.
42+
43+
For PEP8 checking, install the vim-pep8_ plugin, and for pyflakes you can
44+
install vim-pyflakes_. Now you can map the functions `Pep8()` or `Pyflakes()`
45+
to any hotkey or action you want in Vim. Both plugins will display errors at
46+
the bottom of the screen, and provide an easy way to jump to the corresponding
47+
line. It's very handy to call these functions whenever you save a file. In
48+
order to do this, add the following lines to your `vimrc`::
4649

4750
autocmd BufWritePost *.py call Pyflakes()
4851
autocmd BufWritePost *.py call Pep8()
@@ -60,7 +63,10 @@ the following lines into your vimrc::
6063
TextMate
6164
--------
6265

63-
"`TextMate <http://macromates.com/>`_ brings Apple's approach to operating systems into the world of text editors. By bridging UNIX underpinnings and GUI, TextMate cherry-picks the best of both worlds to the benefit of expert scripters and novice users alike."
66+
"`TextMate <http://macromates.com/>`_ brings Apple's approach to operating
67+
systems into the world of text editors. By bridging UNIX underpinnings and GUI,
68+
TextMate cherry-picks the best of both worlds to the benefit of expert
69+
scripters and novice users alike."
6470

6571
Sublime Text
6672
------------
@@ -72,15 +78,19 @@ extraordinary features."
7278
Sublime Text has excellent support for editing Python code and uses Python for
7379
its plugin API.
7480

75-
`Sublime Text 2 <http://www.sublimetext.com/blog/articles/sublime-text-2-beta>`_ is currently in beta.
81+
`Sublime Text 2 <http://www.sublimetext.com/blog/articles/sublime-text-2-beta>`_
82+
is currently in beta.
7683

7784
IDEs
7885
::::
7986

8087
PyCharm / IntelliJ IDEA
8188
-----------------------
8289

83-
`PyCharm <http://www.jetbrains.com/pycharm/>`_ is developed by JetBrains, also known for IntelliJ IDEA. Both share the same code base and most of PyCharm's features can be brought to IntelliJ with the free `Python Plug-In <http://plugins.intellij.net/plugin/?id=631/>`_.
90+
`PyCharm <http://www.jetbrains.com/pycharm/>`_ is developed by JetBrains, also
91+
known for IntelliJ IDEA. Both share the same code base and most of PyCharm's
92+
features can be brought to IntelliJ with the free `Python Plug-In <http://plugins.intellij.net/plugin/?id=631/>`_.
93+
8494

8595
Eclipse
8696
-------
@@ -91,18 +101,28 @@ The most popular Eclipse plugin for Python development is Aptana's
91101

92102
Komodo IDE
93103
-----------
94-
`Komodo IDE <http://www.activestate.com/komodo-ide>`_ is developed by ActiveState and is a commerical IDE for Windows, Mac
104+
`Komodo IDE <http://www.activestate.com/komodo-ide>`_ is developed by
105+
ActiveState and is a commercial IDE for Windows, Mac
95106
and Linux.
96107

108+
97109
Spyder
98110
------
99111

100-
`Spyder <http://code.google.com/p/spyderlib/>`_ an IDE specifically geared toward working with scientific python libraries (namely `Scipy <http://www.scipy.org/>`_).
112+
`Spyder <http://code.google.com/p/spyderlib/>`_ an IDE specifically geared
113+
toward working with scientific python libraries (namely `Scipy <http://www.scipy.org/>`_).
101114
Includes integration with pyflakes_, `pylint <http://www.logilab.org/857>`_,
102115
and `rope <http://rope.sourceforge.net/>`_.
103116

104-
Spyder is open-source (free), offers code completion, syntax highlighting, class and function browser, and object inspection.
117+
Spyder is open-source (free), offers code completion, syntax highlighting,
118+
class and function browser, and object inspection.
119+
120+
121+
WingIDE
122+
-------
105123

124+
`WingIDE <http://wingware.com/>`_ a python specific IDE. Runs for Linux,
125+
Windows, and Mac (as an X11 application, which frustrates some Mac users).
106126

107127

108128
Interpreter Tools
@@ -112,8 +132,10 @@ Interpreter Tools
112132
virtualenv
113133
----------
114134

115-
Virtualenv is a tool to keep the dependencies required by different projects in separate places, by creating virtual Python environments for them.
116-
It solves the "Project X depends on version 1.x but, Project Y needs 4.x" dilemma and keeps your global site-packages directory clean and manageable.
135+
Virtualenv is a tool to keep the dependencies required by different projects
136+
in separate places, by creating virtual Python environments for them.
137+
It solves the "Project X depends on version 1.x but, Project Y needs 4.x"
138+
dilemma and keeps your global site-packages directory clean and manageable.
117139

118140
`virtualenv <http://www.virtualenv.org/en/latest/index.html>`_ creates
119141
a folder which contains all the necessary executables to contain the
@@ -185,7 +207,8 @@ control by adding it to the ignore list.
185207
virtualenvwrapper
186208
-----------------
187209

188-
`Virtualenvwrapper <http://pypi.python.org/pypi/virtualenvwrapper>`_ makes virtualenv a pleasure to use by wrapping the command line API with a nicer CLI.
210+
`Virtualenvwrapper <http://pypi.python.org/pypi/virtualenvwrapper>`_ makes
211+
virtualenv a pleasure to use by wrapping the command line API with a nicer CLI.
189212

190213
::
191214

@@ -198,18 +221,38 @@ Put this into your `~/.bash_profile` (Linux/Mac) file:
198221

199222
$ export VIRTUALENVWRAPPER_VIRTUALENV_ARGS='--no-site-packages'
200223

201-
This will prevent your virtualenvs from relying on your (global) site packages directory, so that they are completely separate..
224+
This will prevent your virtualenvs from relying on your (global) site packages
225+
directory, so that they are completely separate..
202226

203227
Other Tools
204228
:::::::::::
205229

230+
IDLE
231+
----
232+
233+
`IDLE <http://docs.python.org/library/idle.html>`_ is an integrated
234+
development environment that is part of Python standard library. It is
235+
completely written in Python and uses Tkinter GUI toolkit. Though IDLE
236+
is not suited for full-blown development using Python , it is quite
237+
helpful to try out small Python snippets and experiment with different
238+
features in Python.
239+
240+
It provides following features:
241+
242+
* Python Shell Window (interpreter)
243+
* Multi window text editor that colorizes Python code
244+
* Minimal debugging facility
245+
246+
206247
IPython
207248
-------
208249

209-
`IPython <http://ipython.org/>`_ provides a rich toolkit to help you make the most out of using Python interactively. Its main components are:
250+
`IPython <http://ipython.org/>`_ provides a rich toolkit to help you make the
251+
most out of using Python interactively. Its main components are:
210252

211253
* Powerful Python shells (terminal- and Qt-based).
212-
* A web-based notebook with the same core features but support for rich media, text, code, mathematical expressions and inline plots.
254+
* A web-based notebook with the same core features but support for rich media,
255+
text, code, mathematical expressions and inline plots.
213256
* Support for interactive data visualization and use of GUI toolkits.
214257
* Flexible, embeddable interpreters to load into your own projects.
215258
* Tools for high level and interactive parallel computing.
@@ -223,7 +266,8 @@ IPython
223266
BPython
224267
-------
225268

226-
`bpython <http://bpython-interpreter.org/>`_ is an alternative interface to the Python interpreter for Unix-like operating systems. It has the following features:
269+
`bpython <http://bpython-interpreter.org/>`_ is an alternative interface to the
270+
Python interpreter for Unix-like operating systems. It has the following features:
227271

228272
* In-line syntax highlighting.
229273
* Readline-like autocomplete with suggestions displayed as you type.
@@ -238,4 +282,3 @@ BPython
238282

239283
$ pip install bpython
240284

241-

‎docs/dev/virtualenvs.rst

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,3 +137,21 @@ Other useful commands
137137
Shows contents of ``site-packages`` directory.
138138

139139
`Full list of virtualenvwrapper commands <http://www.doughellmann.com/docs/virtualenvwrapper/command_ref.html#managing-environments>`_.
140+
141+
autoenv
142+
-------
143+
When you ``cd`` into a directory containing a ``.env`` `autoenv <https://github.com/kennethreitz/autoenv>`_
144+
automagically activates the environment.
145+
146+
Install it on Mac OS X using ``brew``:
147+
148+
.. code-block:: console
149+
150+
$ brew install autoenv
151+
152+
And on Linux:
153+
154+
.. code-block:: console
155+
156+
$ git clone git://github.com/kennethreitz/autoenv.git ~/.autoenv
157+
$ echo 'source ~/.autoenv/activate.sh' >> ~/.bashrc

‎docs/index.rst

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,13 @@
66
The Hitchhiker's Guide to Python!
77
=================================
88

9-
Welcome to The Hitchhiker's Guide to Python. **DON'T PANIC!**
9+
Welcome to The Hitchhiker's Guide to Python. `DON'T PANIC! <http://www.amazon.com/gp/product/B0043M4ZH0/ref=as_li_ss_tl?ie=UTF8&tag=bookforkind-20&linkCode=as2&camp=1789&creative=390957&creativeASIN=B0043M4ZH0>`_
1010

11-
**This guide is currently under heavy development, and is mostly a skeleton at the moment.** If you'd like to help, `fork us on GitHub <https://github.com/kennethreitz/python-guide>`_!
11+
**This guide is currently under heavy development, and is mostly a skeleton at
12+
the moment.** If you'd like to help, `fork us on GitHub <https://github.com/kennethreitz/python-guide>`_!
1213

13-
This *opinionated* guide exists to provide both novice and expert Python developers a best-practice handbook to the installation, configuration, and usage of Python on a daily basis.
14+
This *opinionated* guide exists to provide both novice and expert Python
15+
developers a best-practice handbook to the installation, configuration, and
16+
usage of Python on a daily basis.
1417

1518
.. include:: contents.rst.inc

‎docs/intro/community.rst

Lines changed: 22 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,40 @@
1+
.. _the_community:
2+
13
The Community
24
=============
35

46
BDFL
57
----
68

7-
Guido van Rossum, the creator of Python, is often referred to as the BDFL — the Benevolent Dictator For Life.
9+
Guido van Rossum, the creator of Python, is often referred to as the BDFL — the
10+
Benevolent Dictator For Life.
811

912

1013

1114
Python Software Foundation
1215
--------------------------
1316

14-
The mission of the Python Software Foundation is to promote, protect, and advance the Python programming language, and to support and facilitate the growth of a diverse and international community of Python programmers.
17+
The mission of the Python Software Foundation is to promote, protect, and
18+
advance the Python programming language, and to support and facilitate the
19+
growth of a diverse and international community of Python programmers.
1520

1621
`Learn More about the PSF <http://www.python.org/psf/>`_.
1722

1823

1924
PEPs
2025
----
2126

22-
PEPs are *Python Enhancement Proposals*. They describe changes to Python itself, or the standards around it.
27+
PEPs are *Python Enhancement Proposals*. They describe changes to Python itself,
28+
or the standards around it.
2329

2430
There are three different types of PEPs (as defined by `PEP1 <http://www.python.org/dev/peps/pep-0001/>`_):
2531

2632
**Standards**
2733
Describes a new feature or implementation.
2834

2935
**Informational**
30-
Describes a design issue, general guidelines, or information to the community.
36+
Describes a design issue, general guidelines, or information to the
37+
community.
3138

3239
**Process**
3340
Describes a process related to Python.
@@ -45,29 +52,35 @@ There are a few PEPs that could be considered required reading:
4552
A list of 19 statements that briefly explain the philosophy behind Python.
4653

4754
- `PEP257 <http://www.python.org/dev/peps/pep-0257/>`_: Docstring Conventions.
48-
Gives guidelines for semantics and conventions associated with Python docstrings.
55+
Gives guidelines for semantics and conventions associated with Python
56+
docstrings.
4957

5058
You can read more at `The PEP Index <http://www.python.org/dev/peps/>`_.
5159

5260
Submitting a PEP
5361
~~~~~~~~~~~~~~~~
5462

55-
PEPs are peer-reviewed and accepted/rejected after much discussion. Anyone can write and submit a PEP for review.
63+
PEPs are peer-reviewed and accepted/rejected after much discussion. Anyone
64+
can write and submit a PEP for review.
5665

5766
Here's an overview of the PEP acceptance workflow:
5867

5968
.. image:: http://www.python.org/dev/peps/pep-0001/pep-0001-1.png
6069

6170

62-
Python Conferences
71+
Python Conferences
6372
--------------------------
6473

65-
The major events for the Python community are developer conferences. The two most notable conferences are PyCon, which is held in the US, and its European sibling, EuroPython.
74+
The major events for the Python community are developer conferences. The two
75+
most notable conferences are PyCon, which is held in the US, and its European
76+
sibling, EuroPython.
6677

6778
A comprehensive list of conferences is maintained `at pycon.org <http://www.pycon.org/>`_.
6879

6980

7081
Python User Groups
7182
--------------------------
7283

73-
User Groups are where a bunch of Python developers meet to present or talk about Python topics of interest. A list of local user groups is maintained at the `Python Software Foundation Wiki <http://wiki.python.org/moin/LocalUserGroups>`_.
84+
User Groups are where a bunch of Python developers meet to present or talk
85+
about Python topics of interest. A list of local user groups is maintained at
86+
the `Python Software Foundation Wiki <http://wiki.python.org/moin/LocalUserGroups>`_.

‎docs/intro/documentation.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,8 @@ The official Python Language and Library documentation can be found here:
1313
Read the Docs
1414
-------------
1515

16-
Read the Docs is a popular community project, providing a single location for all documentation of popular and even more exotic Python modules.
16+
Read the Docs is a popular community project, providing a single location for
17+
all documentation of popular and even more exotic Python modules.
1718

1819
`Read the Docs <http://readthedocs.org/>`_
1920

0 commit comments

Comments
 (0)