diff --git a/docs/index.rst b/docs/index.rst index dcd5657..df7fcb8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,7 +4,7 @@ contain the root `toctree` directive. .. meta:: - :description: An opinionated guide to the Python programming language and a best practice handbook to the installation, configuration, and usage of Python on a daily basis. + :description: An opinionated guide to the Python programming language and a best practice handbook for the installation, configuration, and usage of Python on a daily basis. ################################# @@ -17,7 +17,7 @@ Greetings, Earthling! Welcome to The Hitchhiker's Guide to Python. `fork us on GitHub `_! This handcrafted guide exists to provide both novice and expert Python -developers a best practice handbook to the installation, configuration, and +developers a best practice handbook for the installation, configuration, and usage of Python on a daily basis. This guide is **opinionated** in a way that is almost, but not quite, entirely @@ -25,7 +25,7 @@ This guide is **opinionated** in a way that is almost, but not quite, entirely available here. Rather, you'll find a nice concise list of highly recommended options. -.. note:: The use of **Python 3** is *highly* preferred over Python 2. Consider upgrading your applications and infrastructure if you find yourself *still* using Python 2 in production today. If you are using Python 3, congratulations — you are indeed a person of excellent taste. +.. note:: The use of **Python 3** is *highly* recommended over Python 2. Consider upgrading your applications and infrastructures if you find yourself *still* using Python 2 in production today. If you are using Python 3, congratulations — you are indeed a person of excellent taste. —*Kenneth Reitz* Let's get started! But first, let's make sure you know where your towel is. diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index 4d72a54..27d8540 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -45,7 +45,7 @@ Project Publication Depending on the project, your documentation might include some or all of the following components: -- An *introduction* should show a very short overview of what can be +- An *introduction* should give a very short overview of what can be done with the product, using one or two extremely simplified use cases. This is the thirty-second pitch for your project. @@ -94,7 +94,7 @@ reStructuredText ~~~~~~~~~~~~~~~~ Most Python documentation is written with reStructuredText_. It's like -Markdown with all the optional extensions built in. +Markdown, but with all the optional extensions built in. The `reStructuredText Primer`_ and the `reStructuredText Quick Reference`_ should help you familiarize yourself with its syntax. @@ -149,8 +149,8 @@ a project's documentation. Additionally, Doctest_ will read all embedded docstrings that look like input from the Python commandline (prefixed with ">>>") and run them, checking to see if the output of the command matches the text on the following line. This -allows developers to embed real examples and usage of functions alongside -their source code, and as a side effect, it also ensures that their code is +allows developers to embed real examples and usage of functions alongside +their source code. As a side effect, it also ensures that their code is tested and works. :: @@ -187,8 +187,8 @@ Docstrings are accessible from both the `__doc__` dunder attribute for almost every Python object, as well as with the built in `help()` function. While block comments are usually used to explain *what* a section of code is -doing, or the specifics of an algorithm, docstrings are more intended for -explaining to other users of your code (or you in 6 months time) *how* a +doing, or the specifics of an algorithm, docstrings are more intended towards +explaining other users of your code (or you in 6 months time) *how* a particular function can be used and the general purpose of a function, class, or module. @@ -214,7 +214,7 @@ In larger or more complex projects however, it is often a good idea to give more information about a function, what it does, any exceptions it may raise, what it returns, or relevant details about the parameters. -For more detailed documentation of code a popular style is the one used for the +For more detailed documentation of code a popular style used, is the one used by the NumPy project, often called `NumPy style`_ docstrings. While it can take up more lines than the previous example, it allows the developer to include a lot more information about a method, function, or class. :: diff --git a/docs/writing/gotchas.rst b/docs/writing/gotchas.rst index 677bdf8..f717858 100644 --- a/docs/writing/gotchas.rst +++ b/docs/writing/gotchas.rst @@ -7,13 +7,13 @@ Common Gotchas .. image:: /_static/photos/34435688380_b5a740762b_k_d.jpg For the most part, Python aims to be a clean and consistent language that -avoids surprises. However, there are a few cases that can be confusing to +avoids surprises. However, there are a few cases that can be confusing for newcomers. Some of these cases are intentional but can be potentially surprising. Some could arguably be considered language warts. In general, what follows is a collection of potentially tricky behavior that might seem strange at first -glance, but is generally sensible once you're aware of the underlying cause for +glance, but are generally sensible, once you're aware of the underlying cause for the surprise. @@ -53,8 +53,8 @@ isn't provided, so that the output is:: [12] [42] -What Does Happen -~~~~~~~~~~~~~~~~ +What Actually Happens +~~~~~~~~~~~~~~~~~~~~~ .. testoutput:: @@ -100,6 +100,7 @@ Late Binding Closures Another common source of confusion is the way Python binds its variables in closures (or in the surrounding global scope). + What You Wrote ~~~~~~~~~~~~~~ @@ -125,8 +126,8 @@ variable that multiplies their argument, producing:: 6 8 -What Does Happen -~~~~~~~~~~~~~~~~ +What Actually Happens +~~~~~~~~~~~~~~~~~~~~~ .. testoutput:: @@ -206,7 +207,7 @@ will automatically write a bytecode version of that file to disk, e.g. These ``.pyc`` files should not be checked into your source code repositories. Theoretically, this behavior is on by default for performance reasons. -Without these bytecode files present, Python would re-generate the bytecode +Without these bytecode files, Python would re-generate the bytecode every time the file is loaded.