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 ============= 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 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 ---------- 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? diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index b89944a..21133d8 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. diff --git a/docs/writing/style.rst b/docs/writing/style.rst index 706ee7a..2f8d95f 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 @@ -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