Merge remote-tracking branch 'python-guide/master'

kitelife · kitelife · commit 73d89b300e86 · 2012-06-13T21:29:31.000+08:00
diff --git a/Readme.rst b/Readme.rst
@@ -23,4 +23,6 @@ Topics include:
 - How to interface w/ hg from git easily
 - what libraries to use for what
 
-
+If you are not fond of reading reStructuredText, there is a
+almost up-to-date `HTML version at docs.python-guide.org
+<http://docs.python-guide.org>`_.
diff --git a/docs/_themes/kr/static/flasky.css_t b/docs/_themes/kr/static/flasky.css_t
@@ -528,41 +528,6 @@ a:hover tt {
     }
 }
 
-
-/* scrollbars */
-
-::-webkit-scrollbar {
-    width: 6px;
-    height: 6px;
-}
-
-::-webkit-scrollbar-button:start:decrement,
-::-webkit-scrollbar-button:end:increment {
-    display: block;
-    height: 10px;
-}
-
-::-webkit-scrollbar-button:vertical:increment {
-    background-color: #fff;
-}
-
-::-webkit-scrollbar-track-piece {
-    background-color: #eee;
-    -webkit-border-radius: 3px;
-}
-
-::-webkit-scrollbar-thumb:vertical {
-    height: 50px;
-    background-color: #ccc;
-    -webkit-border-radius: 3px;
-}
-
-::-webkit-scrollbar-thumb:horizontal {
-    width: 50px;
-    background-color: #ccc;
-    -webkit-border-radius: 3px;
-}
-
 /* misc. */
 
 .revsys-inline {
diff --git a/docs/dev/env.rst b/docs/dev/env.rst
@@ -252,7 +252,7 @@ most out of using Python interactively. Its main components are:
 
 * Powerful Python shells (terminal- and Qt-based).
 * A web-based notebook with the same core features but support for rich media,
-text, code, mathematical expressions and inline plots.
+  text, code, mathematical expressions and inline plots.
 * Support for interactive data visualization and use of GUI toolkits.
 * Flexible, embeddable interpreters to load into your own projects.
 * Tools for high level and interactive parallel computing.
diff --git a/docs/intro/duction.rst b/docs/intro/duction.rst
@@ -18,7 +18,7 @@ include:
 
   Python is sometimes described with the words "batteries included"
   for its extensive
-  `stanadard library <http://docs.python.org/library/>`_, which can
+  `standard library <http://docs.python.org/library/>`_, which can
   includes modules for regular expressions, file IO, fraction handling,
   object serialization, and much more.
 
diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst
@@ -4,7 +4,7 @@ Systems Administration
 Fabric
 ------
 
-Fabric is a library for simplifying system administration tasks. While Chef
+`Fabric <http://docs.fabfile.org>`_ 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.
 
@@ -66,16 +66,23 @@ and we can deploy with:
 Additional features include parallel execution, interaction with remote
 programs, and host grouping.
 
+    `Fabric Documentation <http://docs.fabfile.org>`_
+
 Chef
 ----
 
 .. todo:: Write about Chef
 
+    `Chef Documentation
+    <http://wiki.opscode.com/display/chef/Documentation>`_
+
 Puppet
 ------
 
 .. todo:: Write about Puppet
 
+    `Puppet Labs Documentation <http://docs.puppetlabs.com>`_
+
 Blueprint
 ---------
 
@@ -84,4 +91,7 @@ Blueprint
 Buildout
 --------
 
-.. todo:: Write about Buildout
+.. todo:: Write about Buildout
+
+    `Buildout Website <http://www.buildout.org>`_
+
diff --git a/docs/scenarios/scientific.rst b/docs/scenarios/scientific.rst
@@ -11,12 +11,13 @@ and it performs really well.
 
 Due to its high performance nature, scientific computing in python often refers
 to external libraries, typically written in faster languages (like C, or FORTRAN
-for matrix operations). The main libraries used are NumPy and SciPy
+for matrix operations). The main libraries used are `NumPy`_ and
+`SciPy`_.
 
 Libraries
 :::::::::
 
-Numpy
+NumPy
 -----
 `NumPy <http://numpy.scipy.org/>`_ is a low level library written in C (and
 FORTRAN) for high level mathematical functions. NumPy cleverly overcomes the
diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst
@@ -33,7 +33,7 @@ simply run
 
 .. code-block:: console
 
-    $ ruby -e "$(curl -fsS https://raw.github.com/mxcl/homebrew/master/Library/Contributions/install_homebrew.rb)"
+    $ /usr/bin/ruby -e "$(/usr/bin/curl -fsSL https://raw.github.com/mxcl/homebrew/master/Library/Contributions/install_homebrew.rb)"
 
 Then, insert the Homebrew directory at the top of your ``PATH`` enviornment
 variable. You can do this by adding the following line at the bottom of your
diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst
@@ -206,9 +206,12 @@ Sphinx_ is a tool which converts documentation in the :ref:`restructuredtext-ref
 markup language into a range of output formats including HTML, LaTeX (for
 printable PDF versions), manual pages and plain text.
 
-.. note:: This Guide is built with Sphinx_
+There is also a great free hosting for your Sphinx_ docs: `Read The Docs`_
+
+.. note:: This Guide is built with Sphinx_ and hosted on `Read The Docs`_
 
 .. _Sphinx: http://sphinx.pocoo.org
+.. _Read The Docs: http://readthedocs.org
 
 .. _restructuredtext-ref:
 
diff --git a/docs/writing/license.rst b/docs/writing/license.rst
@@ -6,11 +6,26 @@ Open source.
 There are plenty of `open source licenses <http://opensource.org/licenses/alphabetical>`_
 available to choose from.
 
+In general, these licenses tend to fall into one of two categories:
+
+1. licenses that focus more on the user's freedom to do with the
+   software as they please (these are the more-permissive open
+   source licenses such as the MIT, BSD, & Apache), and
+
+2. licenses that focus more on making sure that the code itself —
+   including any changes made to it and distributed along with it —
+   always remains free (these are the less-permissive free software
+   licenses, for example, the GPL and LGPL).
+
+The latter are less-permissive in the sense that they don't permit
+someone to add code to the software and distribute it without also
+including the source code for their changes.
+
 To help you choose one for your project, there's a `license chooser <http://three.org/openart/license_chooser/>`_,
 use it.
 
 
-Non-Restrictive
+More-Permissive
 :::::::::::::::
 
 PSFL
@@ -34,8 +49,8 @@ Apache
 ------
 
 
-Restrictive
-:::::::::::
+Less-Permissive
+:::::::::::::::
 
 
 LGPL
diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst
@@ -9,7 +9,7 @@ Structure is Key
 ----------------
 
 Thanks to the way imports and modules are handled in Python, it is
-relatively easy to structure a python project. Easy, here, means
+relatively easy to structure a Python project. Easy, here, means
 that you do not have many constraints and that the module
 importing model is easy to grasp. Therefore, you are left with the
 pure architectural task of crafting the different parts of your
@@ -19,7 +19,7 @@ Easy structuring of a project means it is also easy
 to do it poorly. Some signs of a poorly structured project
 include:
 
-- Multiple and messy circular dependencies: If your classes
+- Multiple and messy circular dependencies: if your classes
   Table and Chair in furn.py need to import Carpenter from workers.py
   to answer a question such as table.isdoneby(),
   and if conversely the class Carpenter needs to import Table and Chair,
@@ -28,13 +28,13 @@ include:
   fragile hacks such has using import statements inside
   methods or functions.
 
-- Hidden coupling: Each and every change in Table's implementation
+- Hidden coupling: each and every change in Table's implementation
   breaks 20 tests in unrelated test cases because it breaks Carpenter's code,
   which requires very careful surgery to adapt the change. This means
   you have too many assumptions about Table in Carpenter's code or the
   reverse.
 
-- Heavy usage of global state or context: Instead of explicitly
+- Heavy usage of global state or context: instead of explicitly
   passing ``(height, width, type, wood)`` to each other, Table
   and Carpenter rely on global variables that can be modified
   and are modified on the fly by different agents. You need to
@@ -43,14 +43,14 @@ include:
   template code is also modifying this context, messing with
   table dimensions.
 
-- Spaghetti code: Multiple pages of nested if clauses and for loops
+- Spaghetti code: multiple pages of nested if clauses and for loops
   with a lot of copy-pasted procedural code and no
-  proper segmentation are known as spaghetti code. Python's 
+  proper segmentation are known as spaghetti code. Python's
   meaningful indentation (one of its most controversial features) make
   it very hard to maintain this kind of code. So the good news is that
   you might not see too much of it.
 
-- Ravioli code is more likely in Python: It consists of hundreds of
+- Ravioli code is more likely in Python: it consists of hundreds of
   similar little pieces of logic, often classes or objects, without
   proper structure. If you never can remember if you have to use
   FurnitureTable, AssetTable or Table, or even TableNew for your
@@ -186,14 +186,14 @@ objects, they have a type, they can be passed as function arguments, they may
 have methods and properties. In this understanding, Python is an
 object-oriented language.
 
-However, unlike Java, Python do not impose object-oriented programming as the
+However, unlike Java, Python does not impose object-oriented programming as the
 main programming paradigm. It is perfectly viable for a Python project to not
 be object-oriented, i.e. to use no or very few class definitions, class
 inheritance, or any other mechanisms that are specific to object-oriented
 programming.
 
 Moreover, as seen in the modules_ section, the way Python handles modules and
-namespaces gives the developer a natural way to ensure
+namespaces gives the developer a natural way to ensure the
 encapsulation and separation of abstraction layers, both being the most common
 reasons to use object-orientation. Therefore, Python programmers have more
 latitude to not use object-orientation, when it is not required by the business
@@ -208,8 +208,8 @@ In some architectures, typically web applications, multiple instances of Python
 processes are spawned to respond to external requests that can
 happen at the same time. In this case, holding some state into instantiated
 objects, which means keeping some static information about the world, is prone
-to concurrency problems or race-conditions. Sometime between the initialization of the
-state of an object, usually done with the __init__() method, and the actual use
+to concurrency problems or race-conditions. Sometimes, between the initialization of
+the state of an object (usually done with the __init__() method) and the actual use
 of the object state through one of its methods, the world may have changed, and
 the retained state may be outdated. For example, a request may load an item in
 memory and mark it as read by a user. If another request requires the deletion
@@ -230,7 +230,7 @@ in the persistence layer, it is said to have a side-effect.
 Carefully isolating functions with context and side-effects from functions with
 logic (called pure functions) allow the following benefits:
 
-- Pure functions are more likely to be deterministic: given a fixed input,
+- Pure functions are deterministic: given a fixed input,
   the output will always be the same.
 
 - Pure functions are much easier to change or replace if they need to
@@ -257,7 +257,7 @@ The Python language provides a simple yet powerful syntax called 'decorators'.
 A decorator is a function or a class that wraps (or decorate) a function
 or a method. The 'decorated' function or method will replace the original
 'undecorated' function or method. Because functions are first-class objects
-in Python it can be done 'manually' but using the @decorator syntax is
+in Python, it can be done 'manually', but using the @decorator syntax is
 clearer and thus preferred.
 
 .. code-block:: python
diff --git a/docs/writing/style.rst b/docs/writing/style.rst
diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst
