From b531d055d8cf5853175e6349ec66db5ce162332a Mon Sep 17 00:00:00 2001 From: Andrew Macgregor Date: Sun, 14 Oct 2012 10:26:17 +0800 Subject: [PATCH 1/9] making html_tile a unicode string to prevent errors in Sphinx --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index b2bcce8..9361105 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -103,7 +103,7 @@ html_theme_path = ['_themes'] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -html_title = 'The Hitchhiker’s Guide to Python' +html_title = u'The Hitchhiker’s Guide to Python' # A shorter title for the navigation bar. Default is the same as html_title. #html_short_title = None From 6f444414188c0e0b0fffdc2a39be92d18677a4d8 Mon Sep 17 00:00:00 2001 From: Andrew Macgregor Date: Sun, 14 Oct 2012 10:26:17 +0800 Subject: [PATCH 2/9] making html_title a unicode string to prevent errors in Sphinx --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index b2bcce8..9361105 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -103,7 +103,7 @@ html_theme_path = ['_themes'] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -html_title = 'The Hitchhiker’s Guide to Python' +html_title = u'The Hitchhiker’s Guide to Python' # A shorter title for the navigation bar. Default is the same as html_title. #html_short_title = None From 22b85c77c92d46178b094987cc8d071615277b48 Mon Sep 17 00:00:00 2001 From: Andrew Macgregor Date: Mon, 15 Oct 2012 14:12:14 +0800 Subject: [PATCH 3/9] fixed community ref pointed to by intro/duction --- docs/intro/community.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/intro/community.rst b/docs/intro/community.rst index c9635c0..8ae2019 100644 --- a/docs/intro/community.rst +++ b/docs/intro/community.rst @@ -1,4 +1,4 @@ -.. _the_community: +.. _the-community: The Community ============= From 470b548a9a306c55519ca6f036ec7f3df6e2402f Mon Sep 17 00:00:00 2001 From: Andrew Macgregor Date: Mon, 15 Oct 2012 14:42:57 +0800 Subject: [PATCH 4/9] adding a valid label for installation.rst to ref to --- docs/starting/which-python.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/starting/which-python.rst b/docs/starting/which-python.rst index af72adb..2404252 100644 --- a/docs/starting/which-python.rst +++ b/docs/starting/which-python.rst @@ -1,6 +1,8 @@ Picking an Interpreter ====================== +.. _which-python: + Which Python to use? From 773235508755e06fc9b4a0b186b169aeb24a484b Mon Sep 17 00:00:00 2001 From: Andrew Macgregor Date: Tue, 16 Oct 2012 20:44:34 +0800 Subject: [PATCH 5/9] fix minor white space issue causing warning --- docs/intro/learning.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst index 0f38d6e..5425d84 100644 --- a/docs/intro/learning.rst +++ b/docs/intro/learning.rst @@ -65,8 +65,8 @@ Python Koans Python Koans is a port of Edgecase's Ruby Koans. It uses a test-driven approach, q.v. TEST DRIVEN DESIGN SECTION to provide an interactive tutorial -teaching basic python concepts. By fixing assertion statements that fail in a - test script, this provides sequential steps to learning python. +teaching basic python concepts. By fixing assertion statements that fail in a +test script, this provides sequential steps to learning python. For those used to languages and figuring out puzzles on their own, this can be a fun, attractive option. For those new to python and programming, having an From f1651e1dc8e4af70ed67f3681987354cde5e9196 Mon Sep 17 00:00:00 2001 From: Andrew Macgregor Date: Tue, 16 Oct 2012 22:04:15 +0800 Subject: [PATCH 6/9] looks like a typo, was perhaps meant to be link to decorators but that is only a few lines later --- docs/writing/structure.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index 76d0b08..5945174 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -266,7 +266,7 @@ logic (called pure functions) allow the following benefits: - Pure functions are easier to test with unit-tests: There is less need for complex context setup and data cleaning afterwards. -- Pure functions are easier to manipulate, decorate_, and pass-around. +- Pure functions are easier to manipulate, decorate, and pass-around. In summary, pure functions, without any context or side-effects, are more efficient building blocks than classes and objects for some architectures. From d8bc8758135fb59e1e8a46d2c4d48890963f377b Mon Sep 17 00:00:00 2001 From: Andrew Macgregor Date: Tue, 16 Oct 2012 22:10:25 +0800 Subject: [PATCH 7/9] using anonymous hyperlinks to avoid duplicate explicit name warnings see: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#anonymous-hyperlinks --- docs/scenarios/db.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/scenarios/db.rst b/docs/scenarios/db.rst index b17a153..4f03058 100644 --- a/docs/scenarios/db.rst +++ b/docs/scenarios/db.rst @@ -10,8 +10,8 @@ Nearly all Python database modules such as `sqlite3`, `psycopg` and `mysql-python` conform to this interface. Tutorials that explain how to work with modules that conform to this interface can be found -`here `_ and -`here `_. +`here `__ and +`here `__. SQLAlchemy ---------- From f0834bcfaf80849884b0bc1a3772b3b99128b78a Mon Sep 17 00:00:00 2001 From: Andrew Macgregor Date: Tue, 16 Oct 2012 22:21:32 +0800 Subject: [PATCH 8/9] Conventions header was throwing inconsistent level warning. Fixed this and later headings to match rest of page. --- docs/writing/style.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/writing/style.rst b/docs/writing/style.rst index 58ce019..528eb2b 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -416,12 +416,12 @@ Then run it on a file or series of files to get a report of any violations. optparse.py:544:21: W601 .has_key() is deprecated, use 'in' Conventions -::::::::::: +---------------- Here are some conventions you should follow to make your code easier to read. Check if variable equals a constant ------------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You don't need to explicitly compare a value to True, or None, or 0 - you can just add it to the if statement. See `Truth Value Testing @@ -455,7 +455,7 @@ list of what is considered false. print 'attr is None!' Access a Dictionary Element ---------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~ Don't use the ``has_key`` function. Instead use ``x in d`` syntax, or pass a default argument to ``get``. @@ -484,7 +484,7 @@ a default argument to ``get``. print d['hello'] Short Ways to Manipulate Lists ------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ `List comprehensions `_ @@ -548,7 +548,7 @@ manually. Moreover, it is better optimized for iterators. Read From a File ----------------- +~~~~~~~~~~~~~~~~ Use the ``with open`` syntax to read from files. This will automatically close files for you. @@ -574,7 +574,7 @@ The ``with`` statement is better because it will ensure you always close the file, even if an exception is raised. Returning Multiple Values from a Function ------------------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Python supports returning multiple values from a function as a comma-separated list, so you don't have to create an object or dictionary and pack multiple From 655c1bdac9dee02bcf7f1a1a9948d2404cd2709c Mon Sep 17 00:00:00 2001 From: Andrew Macgregor Date: Tue, 16 Oct 2012 23:19:54 +0800 Subject: [PATCH 9/9] provide valid link for YAGNI --- docs/writing/style.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/writing/style.rst b/docs/writing/style.rst index 528eb2b..fbb41a8 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -114,10 +114,10 @@ Those two possibilities are better avoided without any strong reason to not follow the syntax that is the closest to the function definition: ``send('Hello', 'World', cc='Cthulhu', bcc='God')``. -As a side note, following YAGNI_ principle, it is often harder to remove an -optional argument (and its logic inside the function) that was added "just in -case" and is seemingly never used, than to add a new optional argument and its -logic when needed. +As a side note, following `YAGNI `_ +principle, it is often harder to remove an optional argument (and its logic inside the +function) that was added "just in case" and is seemingly never used, than to add a +new optional argument and its logic when needed. The **arbitrary argument list** is the third way to pass arguments to a function. If the function intention is better expressed by a signature with an