diff --git a/docs/dev/env.rst b/docs/dev/env.rst index 6367a57..7d43991 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -16,8 +16,8 @@ Vim is a text editor which uses keyboard shortcuts for editing instead of menus or icons. There exist a couple of plugins and settings for the VIM editor to aid Python development. If you only develop in Python, a good start is to set the default settings for indentation and line-wrapping to values compliant with -`PEP 8 `_. In your home directory, -open a file called `.vimrc` and add the following lines::: +:pep:`8`. In your home directory, open a file called `.vimrc` and add the +following lines::: set textwidth=79 " lines longer than 79 columns will be broken set shiftwidth=4 " operation >> indents 4 columns; << unindents 4 columns diff --git a/docs/intro/community.rst b/docs/intro/community.rst index 8ae2019..05cd148 100644 --- a/docs/intro/community.rst +++ b/docs/intro/community.rst @@ -27,7 +27,7 @@ PEPs PEPs are *Python Enhancement Proposals*. They describe changes to Python itself, or the standards around it. -There are three different types of PEPs (as defined by `PEP1 `_): +There are three different types of PEPs (as defined by :pep:`1`): **Standards** Describes a new feature or implementation. @@ -45,13 +45,13 @@ Notable PEPs There are a few PEPs that could be considered required reading: -- `PEP8 `_: The Python Style Guide. +- :pep:`8`: The Python Style Guide. Read this. All of it. Follow it. -- `PEP20 `_: The Zen of Python. +- :pep:`20`: The Zen of Python. A list of 19 statements that briefly explain the philosophy behind Python. -- `PEP257 `_: Docstring Conventions. +- :pep:`257`: Docstring Conventions. Gives guidelines for semantics and conventions associated with Python docstrings. diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst index b412311..4703f4c 100644 --- a/docs/intro/learning.rst +++ b/docs/intro/learning.rst @@ -65,7 +65,7 @@ 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 +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 @@ -105,7 +105,7 @@ is focused on the more advanced crowd. It starts with topics like decorators (with caching, proxy, and context manager case-studies), method resolution order, using super() and meta-programming, and -general PEP8 best practices. +general :pep:`8` best practices. It has a detailed, multi-chapter case study on writing and releasing a package and eventually an application, including a chapter on using zc.buildout. Later diff --git a/docs/scenarios/db.rst b/docs/scenarios/db.rst index d3c398f..5d12c2a 100644 --- a/docs/scenarios/db.rst +++ b/docs/scenarios/db.rst @@ -5,7 +5,7 @@ DB-API ------ The Python Database API (DB-API) defines a standard interface for Python -database access modules. It's documented in `PEP 249 `_. +database access modules. It's documented in :pep:`249`. Nearly all Python database modules such as `sqlite3`, `psycopg` and `mysql-python` conform to this interface. diff --git a/docs/scenarios/imaging.rst b/docs/scenarios/imaging.rst index 1710432..fa71882 100644 --- a/docs/scenarios/imaging.rst +++ b/docs/scenarios/imaging.rst @@ -12,7 +12,7 @@ The `Python Imaging Library `_, or PIL for short, is *the* library for image manipulation in Python. Unfortunately, its development has stagnated, with its last release in 2009. -Lucky for you, there's an actively-developed fork of PIL called `Pillow `_ - +Luckily for you, there's an actively-developed fork of PIL called `Pillow `_ - it's easier to install, runs on all operating systems, and supports Python 3. Installation diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst index 4ec6647..588dbb2 100644 --- a/docs/scenarios/web.rst +++ b/docs/scenarios/web.rst @@ -18,7 +18,7 @@ interface between web servers and Python web application frameworks. By standardizing behavior and communication between web servers and Python web frameworks, WSGI makes it possible to write portable Python web code that can be deployed in any :ref:`WSGI-compliant web server `. -WSGI is documented in `PEP-3333 `_. +WSGI is documented in :pep:`3333`. Frameworks diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index 7ff5465..d543f53 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -104,9 +104,7 @@ In Python, *docstrings* describe modules, classes, and functions: :: """Returns the square root of self times self.""" ... -In general, follow the `comment section of PEP 0008`_ (the "Python Style Guide"). - -.. _comment section of PEP 0008: http://www.python.org/dev/peps/pep-0008/#comments +In general, follow the comment section of :pep:`8#comments` (the "Python Style Guide"). Commenting Sections of Code ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -137,9 +135,7 @@ operation of the function or class: :: """Returns the square root of self times self.""" ... -.. seealso:: Further reading on docstrings: `PEP 0257`_ - -.. _PEP 0257: http://www.python.org/dev/peps/pep-0257/ +.. seealso:: Further reading on docstrings: :pep:`257` Other Tools diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index 9e56ac1..0a157f9 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -466,9 +466,8 @@ should be your preferred method. .. note:: You can also use the **%** formatting operator to concatenate the pre-determined number of strings besides **join()** and **+**. However, - according to `PEP 3101 `_, - **%** operator became deprecated in Python 3.1 and will be replaced by the - **format()** method in the later versions. + according to :pep:`3101`, the **%** operator became deprecated in + Python 3.1 and will be replaced by the **format()** method in the later versions. .. code-block:: python diff --git a/docs/writing/style.rst b/docs/writing/style.rst index f914649..6718b48 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -117,8 +117,8 @@ 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 +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. 3. The **arbitrary argument list** is the third way to pass arguments to a @@ -256,14 +256,14 @@ are a probable indication that such a refactoring is needed. Idioms ------ -A programming idiom, put simply, is a *way* to write code. The notion of programming idioms +A programming idiom, put simply, is a *way* to write code. The notion of programming idioms is discussed amply at `c2 `_ and at `Stack Overflow `_. -Idiomatic Python code is often referred to as being *Pythonic*. +Idiomatic Python code is often referred to as being *Pythonic*. -Although there usually is one-- and preferably only one --obvious way to do it; +Although there usually is one-- and preferably only one --obvious way to do it; *the* way to write idiomatic Python code can be non-obvious to Python beginners. So, -good idioms must be consciously acquired. +good idioms must be consciously acquired. Some common Python idioms follow: @@ -362,7 +362,7 @@ For more information see this `StackOverflow `_ + :pep:`8` Conforming your Python code to PEP 8 is generally a good idea and helps make code more consistent when working on projects with other developers. There diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst index fdbd671..5c1e6b4 100644 --- a/docs/writing/tests.rst +++ b/docs/writing/tests.rst @@ -16,7 +16,7 @@ Some general rules of testing: alone, and also within the test suite, regardless of the order they are called. The implication of this rule is that each test must be loaded with a fresh dataset and may have to do some cleanup afterwards. This is usually - handled by setUp() and tearDown() methods. + handled by `setUp()` and `tearDown()` methods. - Try hard to make tests that run fast. If one single test needs more than a few millisecond to run, development will be slowed down or the tests will not @@ -287,7 +287,7 @@ always returns the same result (but only for the duration of the test). # not where the SearchForm class itself is imported from @mock.patch('myapp.SearchForm.search', mock_search) def test_new_watchlist_activities(self): - # get_search_results runs a search and iterates over the result + # get_search_results runs a search and iterates over the result self.assertEqual(len(myapp.get_search_results(q="fish")), 3) Mock has many other ways you can configure it and control its behavior.