Merge https://github.com/AaronW/python-guide

Kenneth Reitz · Kenneth Reitz · commit 100a2ad7fd86 · 2011-05-12T02:43:20.000-04:00
diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst
@@ -17,16 +17,29 @@ http://www.riverbankcomputing.co.uk/software/pyqt/download
 
 Cocoa
 :::::
+*Note: The Cocoa framework is only available on Mac OSX. Don't pick this if you're writing a cross-platform application!*
 
 PyObjC
 ------
-*Note: Only available on Mac OSX. Don't pick this if you're writing a cross-platform application.*
+PyObjC 2.0 is included in the default python installation of Mac OS X 10.5 Leopard.
+To install the latest version: ::
+    $ pip install pyobjc 
+or go to http://pyobjc.sourceforge.net/downloads.html
 
 WXPython
 ::::::::
 Install (Stable)
 ----
 *Go to http://www.wxpython.org/download.php#stable and download the appropriate package for your OS.*
+The simplest method to test if it works is to attempt to import it. ::
+    Aarons-MacBook:docs aaron$ python
+    Python 2.6.6 (r266:84374, Aug 31 2010, 11:00:51) 
+    [GCC 4.0.1 (Apple Inc. build 5493)] on darwin
+    >>> import wx
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+    ImportError: No module named wx
+If you don't get the above error, WXPython is installed.
 
 Gtk
 :::
diff --git a/docs/starting/which-python.rst b/docs/starting/which-python.rst
@@ -6,12 +6,12 @@ Which Python to use?
 
 2.x vs 3.x
 ::::::::::
-
+http://wiki.python.org/moin/Python2orPython3
 
 
 History
 -------
-
+Python2.0 was released October 16, 2000.  Python3.0 was released on December 3,2008 and breaks backwards compatibility.
 
 
 Today
diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst
@@ -11,13 +11,51 @@ The Basics
 
 Code Comments
 -------------
-
-
+Information regarding code comments is taken from PEP 008 (http://www.python.org/dev/peps/pep-0008/).
+Block comment styling should be used when commenting out multiple lines of code.: ::
+
+    Block comments generally apply to some (or all) code that follows them,
+    and are indented to the same level as that code.  Each line of a block
+    comment starts with a # and a single space (unless it is indented text
+    inside the comment).
+    Paragraphs inside a block comment are separated by a line containing a
+    single #.
+
+Inline comments are used for individual lines and should be used sparingly.: ::
+
+    An inline comment is a comment on the same line as a statement.  Inline
+    comments should be separated by at least two spaces from the statement.
+    They should start with a # and a single space.
+    Inline comments are unnecessary and in fact distracting if they state
+    the obvious.  Don't do this:
+        x = x + 1                 # Increment x
+    But sometimes, this is useful: ::
+        x = x + 1                 # Compensate for border
 
 Doc Strings
 -----------
+PEP 257 is the primary reference for docstrings. (http://www.python.org/dev/peps/pep-0257/)
+|There are two types of docstrings, one-line and multi-line.  Their names should be fairly self explanatory.
+|One-line docstrings: ::
+
+    def kos_root():
+    """Return the pathname of the KOS root directory."""
+    global _kos_root
+    if _kos_root: return _kos_root
+    ...
+
+Multi-line docstrings: ::
+
+    def complex(real=0.0, imag=0.0):
+    """Form a complex number.
 
+    Keyword arguments:
+    real -- the real part (default 0.0)
+    imag -- the imaginary part (default 0.0)
 
+    """
+    if imag == 0.0 and real == 0.0: return complex_zero
+    ...
 
 Sphinx
 ::::::
