realpython · kennethreitz · Mar 11, 2017 · Mar 11, 2017 · Mar 11, 2017 · Mar 11, 2017
diff --git a/docs/dev/env.rst b/docs/dev/env.rst
@@ -38,7 +38,7 @@ over the syntax file included in Vim 6.1.
 These plugins supply you with a basic environment for developing in Python.
 To get the most out of Vim, you should continually check your code for syntax
 errors and PEP8 compliance. Luckily PEP8_ and Pyflakes_ will do this for you.
-If your Vim is compiled with :option:`+python` you can also utilize some very
+If your Vim is compiled with ``+python`` you can also utilize some very
 handy plugins to do these checks from within the editor.
 
 For PEP8 checking and pyflakes, you can install vim-flake8_. Now you can map the
@@ -151,7 +151,7 @@ versions of PyCharm: Professional Edition (Free 30-day trial) and Community
 Edition (Apache 2.0 License) with fewer features.
 
 Python (on Visual Studio Code)
------------------------------
+------------------------------
 
 `Python for Visual Studio <https://marketplace.visualstudio.com/items?itemName=donjayamanne.python>`_ is an extension for the `Visual Studio Code IDE <https://code.visualstudio.com>`_.
 This is a free, light weight, open source IDE, with support for Mac, Windows, and Linux.

diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst
@@ -93,7 +93,7 @@ where they were placed.
 Other Notes
 ~~~~~~~~~~~
 
-Running ``virtualenv`` with the option :option:`--no-site-packages` will not
+Running ``virtualenv`` with the option ``--no-site-packages`` will not
 include the packages that are installed globally. This can be useful
 for keeping the package list clean in case it needs to be accessed later.
 [This is the default behavior for ``virtualenv`` 1.7 and later.]

diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst
@@ -209,8 +209,10 @@ in Python. Magic methods are surrounded by double underscores (i.e. __init__)
 and can make classes and objects behave in different and magical ways.
 
     `A Guide to Python's Magic Methods <http://www.rafekettler.com/magicmethods.html>`_
+
 .. note:: The Rafekettler.com is currently down, you can go to their Github version directly. Here you can find a PDF version:
     `A Guide to Python's Magic Methods (repo on GitHub) <https://github.com/RafeKettler/magicmethods/blob/master/magicmethods.pdf>`_
+
 
 
 For Engineers and Scientists

diff --git a/docs/intro/news.rst b/docs/intro/news.rst
@@ -49,7 +49,7 @@ delivered in your inbox.  Keep Your Python Programming Skills Updated.
     `Import Python Weekly Newsletter <http://www.importpython.com/newsletter/>`_
 
 Awesome Python Newsletter
-~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A weekly overview of the most popular Python news, articles and packages.
 

diff --git a/docs/scenarios/clibs.rst b/docs/scenarios/clibs.rst
@@ -96,26 +96,27 @@ Example: Overloading __repr__
         std::string getName();
     };
 
+
 :file:`myclass.i`
 
-.. code-block:: c++
+.. code-block:: idl
     :linenos:
 
     %include "string.i"
-
+    
     %module myclass
     %{
     #include <string>
     #include "MyClass.h"
     %}
-
+    
     %extend MyClass {
         std::string __repr__()
         {
             return $self->getName();
         }
     }
-
+    
     %include "MyClass.h"
 
 

diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst
@@ -448,3 +448,4 @@ Multiprocessing
 .. _`threading`: https://docs.python.org/3/library/threading.html
 .. _`stackoverflow post`: http://stackoverflow.com/questions/26688424/python-threads-are-printing-at-the-same-time-messing-up-the-text-output
 .. _`data race`: https://en.wikipedia.org/wiki/Race_condition
+.. _`Lock`: https://docs.python.org/3/library/threading.html#lock-objects
diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst
@@ -10,6 +10,7 @@ Context
 :::::::
 
 
+
 WSGI
 ----
 
@@ -457,7 +458,7 @@ frameworks.
 
 An example template in Mako looks like:
 
-.. code-block:: html
+.. code-block:: mako
 
     <%inherit file="base.html"/>
     <%

diff --git a/docs/shipping/freezing.rst b/docs/shipping/freezing.rst
@@ -60,7 +60,7 @@ py2app      no      no    yes  yes      MIT     no            yes            yes
 .. note::
     All solutions need MS Visual C++ dll to be installed on target machine, except py2app.
     Only Pyinstaller makes self-executable exe that bundles the dll when
-    passing :option:`--onefile` to :file:`Configure.py`.
+    passing ``--onefile`` to :file:`Configure.py`.
 
 Windows
 -------

diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst
@@ -101,7 +101,7 @@ pypiserver
 `Pypiserver <https://pypi.python.org/pypi/pypiserver>`_ is a minimal PyPI
 compatible server.  It can be used to serve a set of packages to easy_install
 or pip.  It includes helpful features like an administrative command
-(:option:`-U`) which will update all its packages to their latest versions
+(``-U``) which will update all its packages to their latest versions
 found on PyPI.
 
 

diff --git a/docs/starting/install3/osx.rst b/docs/starting/install3/osx.rst
@@ -1,3 +1,5 @@
+:orphan: This article should not be added to a toctree for now
+
 .. _install3-osx:
 
 Installing Python 3 on Mac OS X
-Original file line number
+Diff line change
@@ Expand Up / @@ -10,6 +10,7 @@ Context @@
     :::::::
     WSGI
     ----
@@ Expand Down Expand Up / @@ -457,7 +458,7 @@ frameworks. @@
     An example template in Mako looks like:
-    .. code-block:: html
+    .. code-block:: mako
         <%inherit file="base.html"/>
         <%
@@ Expand Down @@