From d84ef20f67e99c06404027f8e02c93a9a9b801a4 Mon Sep 17 00:00:00 2001 From: Aaron Date: Tue, 26 Apr 2011 07:43:04 -0700 Subject: [PATCH 1/4] Added basic comment information, testing markup appearance. --- docs/writing/documentation.rst | 37 ++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index 747d3d7..88e2a18 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -11,13 +11,50 @@ 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 :::::: From 5eeea522151e2f52c4eacabf63a399900008408a Mon Sep 17 00:00:00 2001 From: Aaron Date: Tue, 26 Apr 2011 07:58:07 -0700 Subject: [PATCH 2/4] Attempting to fix markup... --- docs/writing/documentation.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index 88e2a18..e122a83 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -22,20 +22,21 @@ Block comment styling should be used when commenting out multiple lines of code. 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: + 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: :: +|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.""" From 4612c6eb41b1196af4f9ca74143d55775a6083bf Mon Sep 17 00:00:00 2001 From: Aaron Date: Wed, 27 Apr 2011 22:06:46 -0400 Subject: [PATCH 3/4] which-python changes --- docs/scenarios/.DS_Store | Bin 0 -> 6148 bytes docs/scenarios/gui.rst | 15 ++++++++++++++- docs/starting/.DS_Store | Bin 0 -> 6148 bytes docs/starting/which-python.rst | 4 ++-- 4 files changed, 16 insertions(+), 3 deletions(-) create mode 100644 docs/scenarios/.DS_Store create mode 100644 docs/starting/.DS_Store diff --git a/docs/scenarios/.DS_Store b/docs/scenarios/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..afd2f3a3c381cfe62b4b1c0d507eb234d8026440 GIT binary patch literal 6148 zcmeHKOHRW;41F$DKVs7*%Pd(Taf7HTNNnK(kQO1NKoO;4n`3Y&4!~`~^Vo_KLbeE1 zc4fbb=Q%TZQ)My$WVzp*0}B8%y5eZg@QZ1`de26lnGhx2;~8go#SU**Wse<+|EPej z-5ht=;0cdtt>1QCl-q*6`q#LmpVrCP0w!3K-K=$o`}u=ACAS=6%XN?afc+r*OWAa( zYet><4llUpZ!<6(o%u&==2N_rT@0{w?rpY?5f%!B0-?a+DZo8jZFX!JF%$>|LV-pB zeLrM$#oVznOs@`xbOa!dnNG&GelTiH=9oKHhU}qh|&V1&)+_5sWa)=*3 z#77oCp-38?_s>> import wx + Traceback (most recent call last): + File "", line 1, in + ImportError: No module named wx +If you don't get the above error, WXPython is installed. Gtk ::: diff --git a/docs/starting/.DS_Store b/docs/starting/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..31e3a026ae68c9cd2c17bee76325a94b19990fcc GIT binary patch literal 6148 zcmeHK%Sr=55Uh?l1aisI;~u?4@DG*{1+V%8<^>6ateE(^?Fae+{>@r7Ju0i~RYbZ& zPxa1pP45cIn-RSYpNZ z9<%*?|HI|BTFkfAoEehmf_~B@W2C+fv-db)hAn?HMjKS@^Y8!4e-WQPw(Y=48uZ!P#_ct1wsKTz&%?w7&=B93WNfo zz=r}_9}2p#%vd|7rGrhn0uXhKPR3Y=WpRp(Wyac(BQ$d=(W#cN80K{L7dfxYSUWl$ zmMYy5DNS=1*|{4o=*5t zd2jvpdD?3W`VC#CyjlT`aqAGk2dyK=Y0$?D#mp-+){dG*{fSPDgFq4_no!^u6nF!0 Cw?PyD literal 0 HcmV?d00001 diff --git a/docs/starting/which-python.rst b/docs/starting/which-python.rst index f94f4f2..ddb1e40 100644 --- 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 From 8c6fdc871be381872bc448e13b046f7378495801 Mon Sep 17 00:00:00 2001 From: Aaron Date: Wed, 27 Apr 2011 22:10:37 -0400 Subject: [PATCH 4/4] fixing .DS_Store file additions --- docs/scenarios/.DS_Store | Bin 6148 -> 0 bytes docs/starting/.DS_Store | Bin 6148 -> 0 bytes 2 files changed, 0 insertions(+), 0 deletions(-) delete mode 100644 docs/scenarios/.DS_Store delete mode 100644 docs/starting/.DS_Store diff --git a/docs/scenarios/.DS_Store b/docs/scenarios/.DS_Store deleted file mode 100644 index afd2f3a3c381cfe62b4b1c0d507eb234d8026440..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 6148 zcmeHKOHRW;41F$DKVs7*%Pd(Taf7HTNNnK(kQO1NKoO;4n`3Y&4!~`~^Vo_KLbeE1 zc4fbb=Q%TZQ)My$WVzp*0}B8%y5eZg@QZ1`de26lnGhx2;~8go#SU**Wse<+|EPej z-5ht=;0cdtt>1QCl-q*6`q#LmpVrCP0w!3K-K=$o`}u=ACAS=6%XN?afc+r*OWAa( zYet><4llUpZ!<6(o%u&==2N_rT@0{w?rpY?5f%!B0-?a+DZo8jZFX!JF%$>|LV-pB zeLrM$#oVznOs@`xbOa!dnNG&GelTiH=9oKHhU}qh|&V1&)+_5sWa)=*3 z#77oCp-38?_s6ateE(^?Fae+{>@r7Ju0i~RYbZ& zPxa1pP45cIn-RSYpNZ z9<%*?|HI|BTFkfAoEehmf_~B@W2C+fv-db)hAn?HMjKS@^Y8!4e-WQPw(Y=48uZ!P#_ct1wsKTz&%?w7&=B93WNfo zz=r}_9}2p#%vd|7rGrhn0uXhKPR3Y=WpRp(Wyac(BQ$d=(W#cN80K{L7dfxYSUWl$ zmMYy5DNS=1*|{4o=*5t zd2jvpdD?3W`VC#CyjlT`aqAGk2dyK=Y0$?D#mp-+){dG*{fSPDgFq4_no!^u6nF!0 Cw?PyD