From 4b22dd72058ae807269b02145660d8c748b0fffd Mon Sep 17 00:00:00 2001 From: kuyan Date: Tue, 30 Jul 2013 12:35:44 -0700 Subject: [PATCH 01/10] Added note on SublimeLinter. --- docs/dev/env.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/dev/env.rst b/docs/dev/env.rst index 7ec103539..6367a5787 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -113,12 +113,14 @@ scripters and novice users alike." Sublime Text ------------ -"`Sublime Text `_ is a sophisticated text editor -for code, html and prose. You'll love the slick user interface and -extraordinary features." + `Sublime Text `_ is a sophisticated text + editor for code, markup and prose. You'll love the slick user interface, + extraordinary features and amazing performance. Sublime Text has excellent support for editing Python code and uses Python for -its plugin API. +its plugin API. It also has plugins a diverse variety of plugins, `some of which `_ +allow for in-editor PEP8 checking and code "linting". + IDEs :::: From 97c19d8fc40ef799ca09e95c447bb2f79abc4f5f Mon Sep 17 00:00:00 2001 From: kuyan Date: Tue, 30 Jul 2013 12:42:04 -0700 Subject: [PATCH 02/10] Fix link to Contribute page. --- docs/intro/duction.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/intro/duction.rst b/docs/intro/duction.rst index 7b0cf7dda..04cbceb94 100644 --- a/docs/intro/duction.rst +++ b/docs/intro/duction.rst @@ -82,7 +82,6 @@ whether they're an old hand or a first-time Pythonista, and the authors to the Guide will gladly help if you have any questions about the appropriateness, completeness, or accuracy of a contribution. -To get started working on The Hitchhiker's Guide, see -the: doc:`/notes/contribute` page. +To get started working on The Hitchhiker's Guide, see the :doc:`/notes/contribute` page. From 946c9df5ba1c9178cf98eab9abc17b3921cd4a41 Mon Sep 17 00:00:00 2001 From: kuyan Date: Tue, 30 Jul 2013 12:50:49 -0700 Subject: [PATCH 03/10] Update license page with license. --- docs/notes/license.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/notes/license.rst b/docs/notes/license.rst index d26b3c78c..3847e1b8e 100644 --- a/docs/notes/license.rst +++ b/docs/notes/license.rst @@ -1,4 +1,4 @@ License ------- -.. todo:: Determine License \ No newline at end of file +The Guide is licensed under the `Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported license `_. \ No newline at end of file From cbcbce56c89a31affc622ca8fb4f585f36bd3026 Mon Sep 17 00:00:00 2001 From: kuyan Date: Tue, 30 Jul 2013 12:52:07 -0700 Subject: [PATCH 04/10] Fix header to comply with the styleguide. --- docs/notes/license.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/notes/license.rst b/docs/notes/license.rst index 3847e1b8e..5a7f54351 100644 --- a/docs/notes/license.rst +++ b/docs/notes/license.rst @@ -1,4 +1,5 @@ +======= License -------- +======= The Guide is licensed under the `Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported license `_. \ No newline at end of file From b6f014342d8ebdd989c7476ab9e082103be94d26 Mon Sep 17 00:00:00 2001 From: kuyan Date: Tue, 30 Jul 2013 13:05:56 -0700 Subject: [PATCH 05/10] Use the :pep: tag instead of directly linking PEPs --- docs/dev/env.rst | 4 ++-- docs/intro/community.rst | 8 ++++---- docs/intro/learning.rst | 4 ++-- docs/scenarios/db.rst | 2 +- docs/scenarios/imaging.rst | 2 +- docs/scenarios/web.rst | 2 +- docs/writing/documentation.rst | 8 ++------ docs/writing/structure.rst | 5 ++--- docs/writing/style.rst | 16 ++++++++-------- docs/writing/tests.rst | 4 ++-- 10 files changed, 25 insertions(+), 30 deletions(-) diff --git a/docs/dev/env.rst b/docs/dev/env.rst index 6367a5787..7d43991ab 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 8ae20192d..05cd14820 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 b412311ab..4703f4cb3 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 d3c398f82..5d12c2a51 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 171043228..fa718824f 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 4ec664796..588dbb285 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 7ff54654a..d543f53f5 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 9e56ac16f..0a157f94d 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 f9146493a..6718b48f0 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 fdbd6715e..5c1e6b468 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. From d95b26b4e7c30b583fe04a8b9eeb65edb3f90f1e Mon Sep 17 00:00:00 2001 From: kuyan Date: Tue, 30 Jul 2013 13:10:46 -0700 Subject: [PATCH 06/10] Use code tags where needed. --- docs/writing/structure.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index 0a157f94d..d788a08df 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -35,9 +35,9 @@ include: - Multiple and messy circular dependencies: if your classes Table and Chair in furn.py need to import Carpenter from workers.py - to answer a question such as table.isdoneby(), + to answer a question such as ``table.isdoneby()``, and if conversely the class Carpenter needs to import Table and Chair, - to answer the question carpenter.whatdo(), then you + to answer the question ``carpenter.whatdo()``, then you have a circular dependency. In this case you will have to resort to fragile hacks such as using import statements inside methods or functions. @@ -236,7 +236,7 @@ processes are spawned to respond to external requests that can happen at the same time. In this case, holding some state into instantiated objects, which means keeping some static information about the world, is prone to concurrency problems or race-conditions. Sometimes, between the initialization of -the state of an object (usually done with the __init__() method) and the actual use +the state of an object (usually done with the ``__init__()`` method) and the actual use of the object state through one of its methods, the world may have changed, and the retained state may be outdated. For example, a request may load an item in memory and mark it as read by a user. If another request requires the deletion @@ -383,7 +383,7 @@ Python has two kinds of built-in or user-defined types. Mutable types are those that allow in-place modification of the content. Typical mutables are lists and dictionaries: -All lists have mutating methods, like append() or pop(), and +All lists have mutating methods, like ``append()`` or ``pop()``, and can be modified in place. The same goes for dictionaries. Immutable types provide no method for changing their content. @@ -418,7 +418,7 @@ its parts, it is much more efficient to accumulate the parts in a list, which is mutable, and then glue ('join') the parts together when the full string is needed. One thing to notice, however, is that list comprehensions are better and faster than constructing a list in a loop -with calls to append(). +with calls to ``append()``. **Bad** @@ -464,10 +464,10 @@ should be your preferred method. foo = ''.join([foo, 'ooo']) .. note:: - You can also use the **%** formatting operator to concatenate the - pre-determined number of strings besides **join()** and **+**. However, - according to :pep:`3101`, the **%** operator became deprecated in - Python 3.1 and will be replaced by the **format()** method in the later versions. + You can also use the ``%`` formatting operator to concatenate the + pre-determined number of strings besides ``join()`` and ``+``. However, + 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 From 1a77f1bbecdeea4e4f7a91241a7a5139374900a4 Mon Sep 17 00:00:00 2001 From: kuyan Date: Tue, 30 Jul 2013 13:13:05 -0700 Subject: [PATCH 07/10] No need to say 'PEP 8' twice. --- docs/writing/style.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/writing/style.rst b/docs/writing/style.rst index 6718b48f0..49004592f 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -397,9 +397,7 @@ slides from a Python user group PEP 8 ----- -PEP 8 is the de-facto code style guide for Python. - - :pep:`8` +:pep:`8` is the de-facto code style guide for Python. 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 From 6753406a40892ba1b97e4433dde13a22eb028841 Mon Sep 17 00:00:00 2001 From: kuyan Date: Tue, 30 Jul 2013 13:19:31 -0700 Subject: [PATCH 08/10] Declare code block language, fix formatting --- docs/writing/tests.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/writing/tests.rst b/docs/writing/tests.rst index 5c1e6b468..a5ac785d0 100644 --- a/docs/writing/tests.rst +++ b/docs/writing/tests.rst @@ -112,7 +112,7 @@ test suite runs. A simple doctest in a function: -:: +.. code-block:: python def square(x): """Squares x. @@ -142,7 +142,7 @@ py.test py.test is a no-boilerplate alternative to Python's standard unittest module. -:: +.. code-block:: console $ pip install pytest @@ -150,7 +150,7 @@ Despite being a fully-featured and extensible test tool, it boasts a simple syntax. Creating a test suite is as easy as writing a module with a couple of functions -:: +.. code-block:: console # content of test_sample.py def func(x): @@ -161,7 +161,7 @@ functions and then running the `py.test` command -:: +.. code-block:: console $ py.test =========================== test session starts ============================ @@ -193,7 +193,7 @@ Nose nose extends unittest to make testing easier. -:: +.. code-block:: console $ pip install nose @@ -210,7 +210,7 @@ tox tox is a tool for automating test environment management and testing against multiple interpreter configurations -:: +.. code-block:: console $ pip install tox @@ -227,14 +227,14 @@ API and better assertions over the one available in previous versions of Python. If you're using Python 2.6 or below, you can install it with pip -:: +.. code-block:: console $ pip install unittest2 You may want to import the module under the name unittest to make porting code to newer versions of the module easier in the future -:: +.. code-block:: python import unittest2 as unittest @@ -253,7 +253,7 @@ mock mock is a library for testing in Python. -:: +.. code-block:: console $ pip install mock @@ -262,7 +262,7 @@ make assertions about how they have been used. For example, you can monkey patch a method -:: +.. code-block:: console from mock import MagicMock thing = ProductionClass() @@ -275,7 +275,7 @@ To mock classes or objects in a module under test, use the ``patch`` decorator. In the example below, an external search system is replaced with a mock that always returns the same result (but only for the duration of the test). -:: +.. code-block:: console def mock_search(self): class MockSearchQuerySet(SearchQuerySet): From 4428d875c1897a575e2b0bb40d5b3df1ee8a8b23 Mon Sep 17 00:00:00 2001 From: kuyan Date: Tue, 30 Jul 2013 13:23:47 -0700 Subject: [PATCH 09/10] Highlight examples as ReStructuredText. --- docs/notes/styleguide.rst | 56 ++++++++++++++++++++++++++++----------- 1 file changed, 40 insertions(+), 16 deletions(-) diff --git a/docs/notes/styleguide.rst b/docs/notes/styleguide.rst index 958382c18..46fbfdf7f 100644 --- a/docs/notes/styleguide.rst +++ b/docs/notes/styleguide.rst @@ -39,24 +39,32 @@ Headings Use the following styles for headings. -Chapter title:: +Chapter title: + +.. code-block:: rest ######### Chapter 1 ######### -Page title:: +Page title: + +.. code-block:: rest =================== Time is an Illusion =================== -Section headings:: +Section headings: + +.. code-block:: rest Lunchtime Doubly So ------------------- -Sub section headings:: +Sub section headings: + +.. code-block:: rest Very Deep ~~~~~~~~~ @@ -74,7 +82,9 @@ Code Examples Wrap all code examples at 70 characters to avoid horizontal scrollbars. -Command line examples:: +Command line examples: + +.. code-block:: rest .. code-block:: console @@ -83,7 +93,9 @@ Command line examples:: Be sure to include the ``$`` prefix before each line. -Python interpreter examples:: +Python interpreter examples: + +.. code-block:: rest Label the example:: @@ -91,7 +103,9 @@ Python interpreter examples:: >>> import this -Python examples:: +Python examples: + +.. code-block:: rest Descriptive title:: @@ -103,16 +117,20 @@ Python examples:: Externally Linking ------------------ -* Prefer labels for well known subjects (ex: proper nouns) when linking:: +* Prefer labels for well known subjects (ex: proper nouns) when linking: + + .. code-block:: rest - Sphinx_ is used to document Python. + Sphinx_ is used to document Python. - .. _Sphinx: http://sphinx.pocoo.org + .. _Sphinx: http://sphinx.pocoo.org * Prefer to use descriptive labels with inline links instead of leaving bare - links:: + links: + + .. code-block:: rest - Read the `Sphinx Tutorial `_ + Read the `Sphinx Tutorial `_ * Avoid using labels such as "click here", "this", etc. preferring descriptive labels (SEO worthy) instead. @@ -124,7 +142,9 @@ To cross-reference other parts of this documentation, use the `:ref: `_ keyword and labels. -To make reference labels more clear and unique, always add a ``-ref`` suffix:: +To make reference labels more clear and unique, always add a ``-ref`` suffix: + +.. code-block:: rest .. _some-section-ref: @@ -137,14 +157,18 @@ Notes and Warnings Make use of the appropriate `admonitions directives `_ when making notes. -Notes:: +Notes: + +.. code-block:: rest .. note:: The Hitchhiker’s Guide to the Galaxy has a few things to say on the subject of towels. A towel, it says, is about the most massively useful thing an interstellar hitch hiker can have. -Warnings:: +Warnings: + +.. code-block:: rest .. warning:: DON'T PANIC @@ -156,7 +180,7 @@ Please mark any incomplete areas of The Guide with a `todo directive avoid cluttering the :ref:`todo-list-ref`, use a single ``todo`` for stub documents or large incomplete sections. -:: +.. code-block:: rest .. todo:: Learn the Ultimate Answer to the Ultimate Question From 9072b68de4440cec7d5df095048e34b54a287686 Mon Sep 17 00:00:00 2001 From: kuyan Date: Tue, 30 Jul 2013 13:39:51 -0700 Subject: [PATCH 10/10] more code tags. --- docs/writing/structure.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index d788a08df..465097bfb 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -448,10 +448,10 @@ with calls to ``append()``. nums = [str(n) for n in range(20)] print "".join(nums) -One final thing to mention about strings is that using join() is not always +One final thing to mention about strings is that using ``join()`` is not always best. In the instances where you are creating a new string from a pre-determined number of strings, using the addition operator is actually faster, but in cases -like above or in cases where you are adding to an existing string, using join() +like above or in cases where you are adding to an existing string, using ``join()`` should be your preferred method. .. code-block:: python