diff --git a/docs/dev/env.rst b/docs/dev/env.rst index 56301fc..7ec1035 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -14,7 +14,7 @@ VIM Vim is a text editor which uses keyboard shortcuts for editing instead of menus or icons. There exist a couple of plugins and settings for the VIM editor to -aid python development. If you only develop in Python, a good start is to set +aid Python development. If you only develop in Python, a good start is to set the default settings for indentation and line-wrapping to values compliant with `PEP 8 `_. In your home directory, open a file called `.vimrc` and add the following lines::: @@ -29,7 +29,7 @@ open a file called `.vimrc` and add the following lines::: With these settings, newlines are inserted after 79 characters and indentation is set to 4 spaces per tab. If you also use VIM for other languages, there is a -handy plugin at indent_, which handles indentation settings for python source +handy plugin at indent_, which handles indentation settings for Python source files. There is also a handy syntax plugin at syntax_ featuring some improvements over @@ -67,12 +67,12 @@ Python-mode Python-mode_ is a complex solution in VIM for working with python code. It has: -- Async python code checking (pylint, pyflakes, pep8, mccabe) in any combination +- Asynchronous Python code checking (pylint, pyflakes, pep8, mccabe) in any combination - Code refactoring and autocompletion with Rope -- Fast python folding +- Fast Python folding - Virtualenv support -- Search by python documentation and run python code -- Auto pep8 error fixes +- Search by Python documentation and run Python code +- Auto PEP8 error fixes And more. @@ -148,7 +148,7 @@ Spyder ------ `Spyder `_ is an IDE specifically geared -toward working with scientific python libraries (namely `Scipy `_). +toward working with scientific Python libraries (namely `Scipy `_). It includes integration with pyflakes_, `pylint `_, and `rope `_. @@ -159,7 +159,7 @@ class and function browser, and object inspection. WingIDE ------- -`WingIDE `_ is a python specific IDE. It runs on Linux, +`WingIDE `_ is a Python specific IDE. It runs on Linux, Windows, and Mac (as an X11 application, which frustrates some Mac users). WingIDE offers code completion, syntax highlighting, source browser, graphical diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index 3397d66..481b341 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -4,13 +4,14 @@ Systems Administration Fabric ------ -`Fabric `_ is a library for simplifying system administration tasks. While Chef -and Puppet tend to focus on managing servers and system libraries, -fabric is more focused on application level tasks such as deployment. +`Fabric `_ is a library for simplifying system +administration tasks. While Chef and Puppet tend to focus on managing servers +and system libraries, fabric is more focused on application level tasks such +as deployment. Install Fabric: -.. code-block:: bash +.. code-block:: console $ pip install fabric @@ -40,7 +41,7 @@ server. With the previous code saved in a file named fabfile.py, we can check memory usage with: -.. code-block:: bash +.. code-block:: console $ fab memory_usage [my_server1] Executing task 'memory' @@ -59,7 +60,7 @@ usage with: and we can deploy with: -.. code-block:: bash +.. code-block:: console $ fab deploy @@ -78,7 +79,7 @@ multiple servers using simple template files. Salt supports python versions 2.6 and 2.7 and can be installed via pip: -.. code-block:: bash +.. code-block:: console $ pip install salt @@ -87,7 +88,7 @@ shell commands or use pre-built modules of complex commands on our minions. The following command lists all available minion hosts, using the ping module. -.. code-block:: bash +.. code-block:: console $ salt '*' test.ping @@ -98,7 +99,7 @@ provide a host taxonomy for the salt modules. The following command lists all available minions running CentOS using the grains system: -.. code-block:: bash +.. code-block:: console $ salt -G 'os:CentOS' test.ping diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst index 49dd0ad..7194f57 100644 --- a/docs/scenarios/gui.rst +++ b/docs/scenarios/gui.rst @@ -29,14 +29,18 @@ PyObjC wxPython -------- -wxPython is a GUI toolkit for the Python programming language. It allows Python programmers to create programs with a robust, highly functional graphical user interface, simply and easily. It is implemented as a Python extension module (native code) that wraps the popular wxWidgets cross platform GUI library, which is written in C++. +wxPython is a GUI toolkit for the Python programming language. It allows +Python programmers to create programs with a robust, highly functional +graphical user interface, simply and easily. It is implemented as a Python +extension module (native code) that wraps the popular wxWidgets cross platform +GUI library, which is written in C++. Install (Stable) ~~~~~~~~~~~~~~~~ *Go to http://www.wxpython.org/download.php#stable and download the appropriate package for your OS.* -Gtk +GTk --- PyGTK provides Python bindings for the GTK+ toolkit. Like the GTK+ library itself, it is currently licensed under the GNU LGPL. It is worth noting that @@ -60,10 +64,15 @@ available on the `Python Wiki `_. Kivy ---- -`Kivy `_ is a Python library for development of multi-touch enabled media rich applications. The aim is to allow for quick and easy interaction design and rapid prototyping, while making your code reusable and deployable. +`Kivy `_ is a Python library for development of multi-touch +enabled media rich applications. The aim is to allow for quick and easy +interaction design and rapid prototyping, while making your code reusable +and deployable. -Kivy is written in Python, based on OpenGL and supports different input devices such as: Mouse, Dual Mouse, TUIO, WiiMote, WM_TOUCH, HIDtouch, Apple's products and so on. +Kivy is written in Python, based on OpenGL and supports different input devices +such as: Mouse, Dual Mouse, TUIO, WiiMote, WM_TOUCH, HIDtouch, Apple's products and so on. -Kivy is actively being developed by a community and free to use. It operates on all major platforms (Linux, OSX, Windows, Android). +Kivy is actively being developed by a community and free to use. It operates +on all major platforms (Linux, OSX, Windows, Android). The main resource for information is the website: http://kivy.org diff --git a/docs/scenarios/network.rst b/docs/scenarios/network.rst index b01c0ef..56031aa 100644 --- a/docs/scenarios/network.rst +++ b/docs/scenarios/network.rst @@ -4,10 +4,10 @@ Networking Twisted ------- -`Twisted `_ is an event-driven networking engine. It can be -used to build applications around many different networking protocols, including http servers -and clients, applications using SMTP, POP3, IMAP or SSH protocols, instant messaging and -`many more `_. +`Twisted `_ is an event-driven networking +engine. It can be used to build applications around many different networking +protocols, including http servers and clients, applications using SMTP, POP3, +IMAP or SSH protocols, instant messaging and `much more `_. PyZMQ ----- diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index 2384a64..6d2a156 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -26,6 +26,11 @@ by downloading `XCode `_, the smaller Apple account) or the even smaller `OSX-GCC-Installer `_ package. +.. note:: + If you already have XCode installed, do not install OSX-GCC-Installer. + In combination, the software can cause issues that are difficult to + diagnose. + While Lion comes with a large number of UNIX utilities, those familiar with Linux systems will notice one key component missing: a decent package manager. `Homebrew `_ fills this void. diff --git a/docs/starting/which-python.rst b/docs/starting/which-python.rst index e07ad4b..2fc8525 100644 --- a/docs/starting/which-python.rst +++ b/docs/starting/which-python.rst @@ -47,11 +47,11 @@ level of compatibility with Python packages and C extension modules. If you are writing open-source Python code and want to reach the widest possible audience, targeting CPython is your best bet. If you need to use any packages -that rely on C extensions for their functionality (eg: numpy) then CPython +that rely on C extensions for their functionality (e.g. numpy) then CPython is your only choice. Being the reference implementation, all versions of the Python language are -available as CPython. Python 3 is only available in a CPython implementation. +available as CPython. Python 3 is only available as a CPython implementation. PyPy ---- @@ -73,14 +73,14 @@ Jython ------ `Jython `_ is a Python implementation that compiles -Python code to Java byte code that then executes on a JVM. It has the additional -advantage of being able to import and use any Java class the same as a Python +Python code to Java byte code that is then executed in a JVM. It has the additional +advantage of being able to import and use any Java class like a Python module. If you need to interface with an existing Java codebase or have other reasons to need to write Python code for the JVM, Jython is the best choice. -Currently Jython supports up to Python 2.5. [#jython_ver]_ +Jython currently supports up to Python 2.5. [#jython_ver]_ IronPython ---------- @@ -90,7 +90,7 @@ framework. It can use both Python and .NET framework libraries, and can also expose Python code to other .NET languages. `Python Tools for Visual Studio `_ integrates -IronPython directly in to the Visual Studio development environment, making it +IronPython directly into the Visual Studio development environment, making it an ideal choice for Windows developers. IronPython supports Python 2.7. [#iron_ver]_ diff --git a/docs/writing/gotchas.rst b/docs/writing/gotchas.rst index 45c0e56..d96d3d8 100644 --- a/docs/writing/gotchas.rst +++ b/docs/writing/gotchas.rst @@ -2,11 +2,11 @@ Common Gotchas ============== For the most part, Python aims to be a clean and consistent language that -avoids surprises, but there are a few cases where newcomers to the language -often get tripped up. +avoids surprises. However, there are a few cases that can be confusing to +newcomers. -Some of these are intentional but potentially surprising. Some could arguably -be considered language warts. In general though, what follows is a collection +Some of these cases are intentional but can be potentially surprising. Some +could arguably be considered language warts. In general though, what follows is a collection of potentially tricky behavior that might seem strange at first glance, but is generally sensible once you're aware of the underlying cause for the surprise. @@ -157,7 +157,7 @@ What You Should Do Instead ~~~~~~~~~~~~~~~~~~~~~~~~~~ The most general solution is arguably a bit of a hack. Due to Python's -afformentioned behavior concerning evaluating default arguments to functions +aforementioned behavior concerning evaluating default arguments to functions (see :ref:`default_args`), you can create a closure that binds immediately to its arguments by using a default arg like so: