From cad494fd407571362ba2b7c284b009316d74b6cb Mon Sep 17 00:00:00 2001 From: Aaron Date: Tue, 26 Apr 2011 13:16:04 +0800 Subject: [PATCH 1/5] GUI info added --- docs/scenarios/gui.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst index 17273c7..291bcc9 100644 --- a/docs/scenarios/gui.rst +++ b/docs/scenarios/gui.rst @@ -21,6 +21,9 @@ PyObjC WXPython :::::::: +Install (Stable) +---- +*Go to http://www.wxpython.org/download.php#stable and download the appropriate package for your OS. Gtk ::: From 4293cf6a561d0e10f1b8f2a55e5255bbf29d12f8 Mon Sep 17 00:00:00 2001 From: Aaron Date: Tue, 26 Apr 2011 13:16:28 +0800 Subject: [PATCH 2/5] Edited docs/scenarios/gui.rst via GitHub --- docs/scenarios/gui.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst index 291bcc9..da25c1b 100644 --- a/docs/scenarios/gui.rst +++ b/docs/scenarios/gui.rst @@ -23,7 +23,7 @@ WXPython :::::::: Install (Stable) ---- -*Go to http://www.wxpython.org/download.php#stable and download the appropriate package for your OS. +*Go to http://www.wxpython.org/download.php#stable and download the appropriate package for your OS.* Gtk ::: From 15571061559cb0c95d720d9ca3d8f602ed07882b Mon Sep 17 00:00:00 2001 From: Aaron Date: Tue, 26 Apr 2011 13:25:46 +0800 Subject: [PATCH 3/5] Added more basic GUI info. --- docs/scenarios/gui.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst index da25c1b..22dcfc4 100644 --- a/docs/scenarios/gui.rst +++ b/docs/scenarios/gui.rst @@ -4,20 +4,23 @@ GUI Applications Qt :: +Qt is a cross-platform application framework that is widely used for developing software with a GUI but can also be used for non-GUI applications. PySide ------ +http://developer.qt.nokia.com/wiki/PySideDownloads/ PyQt ---- - +*Note: If your software does not fully comply with the GPL you will need a commercial license!* +http://www.riverbankcomputing.co.uk/software/pyqt/download Cocoa ::::: PyObjC ------ - +*Note: Only available on Mac OSX. Don't pick this if you're writing a cross-platform application.* WXPython :::::::: From 9a8f760530d7fc35512c5d518626cd1405e0b937 Mon Sep 17 00:00:00 2001 From: Aaron Date: Tue, 26 Apr 2011 22:43:04 +0800 Subject: [PATCH 4/5] 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 fb3031f20d2b97b25dd59439d0ad95497f0cd23b Mon Sep 17 00:00:00 2001 From: Aaron Date: Tue, 26 Apr 2011 22:58:07 +0800 Subject: [PATCH 5/5] 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."""