Fixed all H2 headings

Before, H2 fomratting was not consistent. Now, all H2 headings use over/under asterisks.
2026-06-05 14:50:19 +00:00 · 2018-12-04 13:44:41 -07:00
parent 58fe178325
commit 35c13bc9ea
43 changed files with 532 additions and 203 deletions
@@ -7,16 +7,19 @@ The Community

 .. image:: /_static/photos/34689432801_78d97ecec9_k_d.jpg

+
+****
 BDFL
----
+****

 Guido van Rossum, the creator of Python, is often referred to as the BDFL — the
 Benevolent Dictator For Life.


-
+**************************
 Python Software Foundation
--------------------------
+**************************
+

 The mission of the Python Software Foundation is to promote, protect, and
 advance the Python programming language, and to support and facilitate the
@@ -25,8 +28,9 @@ growth of a diverse and international community of Python programmers.
 `Learn More about the PSF <http://www.python.org/psf/>`_.


+****
 PEPs
----
+****

 PEPs are *Python Enhancement Proposals*. They describe changes to Python itself,
 or the standards around it.
@@ -72,8 +76,9 @@ Here's an overview of the PEP acceptance workflow:
 .. image:: ../_static/pep-0001-1.png


+******************
 Python Conferences
------------------
+******************

 The major events for the Python community are developer conferences. The two
 most notable conferences are PyCon, which is held in the US, and its European
@@ -82,16 +87,18 @@ sibling, EuroPython.
 A comprehensive list of conferences is maintained at `pycon.org <http://www.pycon.org/>`_.


+******************
 Python User Groups
------------------
+******************

 User Groups are where a bunch of Python developers meet to present or talk
 about Python topics of interest. A list of local user groups is maintained at
 the `Python Software Foundation Wiki <http://wiki.python.org/moin/LocalUserGroups>`_.


+******************
 Online Communities
------------------
+******************

 `PythonistaCafe <https://www.pythonistacafe.com>`_ is an invite-only, online community
 of Python and software development enthusiasts helping each other succeed and grow.
@@ -99,8 +106,9 @@ Think of it as a club of mutual improvement for Pythonistas where a broad range
 programming questions, career advice, and other topics are discussed every day.


+*****************
 Python Job Boards
-----------------
+*****************

 `Python Jobs HQ <https://www.pythonjobshq.com>`_ is a Python job board, by Python Developers
 for Python Developers. The site aggregates Python job postings from across the web and
@@ -6,8 +6,10 @@ Documentation

 .. image:: /_static/photos/33928823133_2f3d32cf32_k_d.jpg

+
+**********************
 Official Documentation
----------------------
+**********************

 The official Python Language and Library documentation can be found here:

@@ -15,8 +17,9 @@ The official Python Language and Library documentation can be found here:
    - `Python 3.x <https://docs.python.org/3/>`_


+*************
 Read the Docs
-------------
+*************

 Read the Docs is a popular community project that hosts documentation
 for open source software. It holds documentation for many Python modules,
@@ -25,8 +28,9 @@ both popular and exotic.
    `Read the Docs <https://readthedocs.org/>`_


+*****
 pydoc
-----
+*****

 :program:`pydoc` is a utility that is installed when you install Python.
 It allows you to quickly retrieve and search for documentation from your
@@ -59,8 +59,10 @@ include:

 .. _about-ref:

+
+****************
 About This Guide
----------------
+****************

 Purpose
 ~~~~~~~
@@ -6,8 +6,10 @@ Learning Python

 .. image:: /_static/photos/32800783863_11a00db52c_k_d.jpg

+
+********
 Beginner
--------
+********

 The Python Tutorial
 ~~~~~~~~~~~~~~~~~~~~
@@ -195,8 +197,9 @@ making the process of learning Python fun and engaging.
    `Code the blocks <https://codetheblocks.com/tutorials/introduction>`_


+************
 Intermediate
------------
+************

 Python Tricks: The Book
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -218,8 +221,9 @@ programmers.
    `Effective Python <http://www.effectivepython.com/>`_


+********
 Advanced
--------
+********

 Pro Python
 ~~~~~~~~~~
@@ -261,9 +265,9 @@ and can make classes and objects behave in different and magical ways.
    `A Guide to Python's Magic Methods (repo on GitHub) <https://github.com/RafeKettler/magicmethods/blob/master/magicmethods.pdf>`_


-
+****************************
 For Engineers and Scientists
----------------------------
+****************************

 A Primer on Scientific Programming with Python
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -282,8 +286,10 @@ puts the emphasis on numerical methods and how to implement them in Python.

    `Numerical Methods in Engineering with Python <http://www.cambridge.org/us/academic/subjects/engineering/engineering-mathematics-and-programming/numerical-methods-engineering-python-2nd-edition>`_

+
+********************
 Miscellaneous Topics
--------------------
+********************

 Problem Solving with Algorithms and Data Structures
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -339,8 +345,9 @@ PythonistaCafe is an invite-only, online community of Python and software develo
    `PythonistaCafe <https://www.pythonistacafe.com>`_


+**********
 References
----------
+**********

 Python in a Nutshell
 ~~~~~~~~~~~~~~~~~~~~
@@ -6,76 +6,96 @@ News

 .. image:: /_static/photos/33573767786_eececc5d27_k_d.jpg

+
+****************
 PyCoder’s Weekly
-~~~~~~~~~~~~~~~~
+****************

 PyCoder’s Weekly is a free weekly Python newsletter for Python developers
 by Python developers (Projects, Articles, News, and Jobs).

    `PyCoder’s Weekly <https://pycoders.com/>`_

+
+***********
 Real Python
-~~~~~~~~~~~
+***********

 At Real Python you can learn all things Python from the ground up, with weekly free and in-depth tutorials. Everything from the absolute basics of Python, to web development and web scraping, to data visualization, and beyond.

    `Real Python <https://realpython.com/>`_

+
+*************
 Planet Python
-~~~~~~~~~~~~~
+*************

 This is an aggregate of Python news from a growing number of developers.

    `Planet Python <http://planet.python.org>`_

+
+*********
 /r/python
-~~~~~~~~~
+*********

 /r/python is the Reddit Python community where users contribute and vote on
 Python-related news.

    `/r/python <http://reddit.com/r/python>`_

+
+*******************
 Talk Python Podcast
-~~~~~~~~~~~~~~~~~~~
+*******************

 The #1 Python-focused podcast covering the people and ideas in Python.

    `Talk Python To Me <https://talkpython.fm>`_

+
+********************
 Python Bytes Podcast
-~~~~~~~~~~~~~~~~~~~~
+********************

 A short-form Python podcast covering recent developer headlines.

    `Python Bytes <https://pythonbytes.fm>`_

+
+*************
 Python Weekly
-~~~~~~~~~~~~~
+*************

 Python Weekly is a free weekly newsletter featuring curated news, articles,
 new releases, jobs, etc. related to Python.

    `Python Weekly <http://www.pythonweekly.com/>`_

+
+***********
 Python News
-~~~~~~~~~~~~~
+***********

 Python News is the news section in the official Python web site
 (www.python.org). It briefly highlights the news from the Python community.

    `Python News <http://www.python.org/news/>`_

+
+********************
 Import Python Weekly
-~~~~~~~~~~~~~~~~~~~~
+********************

 Weekly Python Newsletter containing Python Articles, Projects, Videos, Tweets
 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.

@@ -11,15 +11,19 @@ issue on GitHub_. To submit patches, please send a pull request on GitHub_.
 Once your changes get merged back in, you'll automatically be added to the
 `Contributors List <https://github.com/kennethreitz/python-guide/contributors>`_.

+
+***********
 Style Guide
-----------
+***********

 For all contributions, please follow the :ref:`guide-style-guide`.

 .. _todo-list-ref:

+
+*********
 Todo List
---------
+*********

 If you'd like to contribute, there's plenty to do. Here's a short todo_ list.

@@ -19,8 +19,10 @@ The Guide is written as :ref:`restructuredtext-ref`.
 .. note:: On any page of the rendered HTML you can click "Show Source" to
   see how authors have styled the page.

+
+*********
 Relevancy
---------
+*********

 Strive to keep any contributions relevant to the :ref:`purpose of The Guide
 <about-ref>`.
@@ -36,8 +38,10 @@ Strive to keep any contributions relevant to the :ref:`purpose of The Guide
  resources, and describe why it's useful to Python.
 * When in doubt, ask.

+
+********
 Headings
--------
+********

 Use the following styles for headings.

@@ -71,8 +75,10 @@ Sub section headings:
    Very Deep
    ~~~~~~~~~

+
+*****
 Prose
-----
+*****

 Wrap text lines at 78 characters. Where necessary, lines may exceed 78
 characters, especially if wrapping would make the source text more difficult
@@ -85,8 +91,10 @@ from this project, due to complete and total lack of taste.

 Banishment? Is this a joke? Hopefully we will never have to find out.

+
+*************
 Code Examples
-------------
+*************

 Wrap all code examples at 70 characters to avoid horizontal scrollbars.

@@ -122,8 +130,10 @@ Python examples:
        def get_answer():
            return 42

+
+******************
 Externally Linking
------------------
+******************

 * Prefer labels for well known subjects (ex: proper nouns) when linking:

@@ -143,8 +153,10 @@ Externally Linking
 * Avoid using labels such as "click here", "this", etc. preferring
  descriptive labels (SEO worthy) instead.

+
+********************************
 Linking to Sections in The Guide
--------------------------------
+********************************

 To cross-reference other parts of this documentation, use the `:ref:
 <http://sphinx.pocoo.org/markup/inline.html#cross-referencing-arbitrary-locations>`_
@@ -159,8 +171,10 @@ To make reference labels more clear and unique, always add a ``-ref`` suffix:
    Some Section
    ------------

+
+******************
 Notes and Warnings
------------------
+******************

 Make use of the appropriate `admonitions directives
 <http://sphinx.pocoo.org/rest.html#directives>`_ when making notes.
@@ -180,8 +194,10 @@ Warnings:

    .. warning:: DON'T PANIC

+
+*****
 TODOs
-----
+*****

 Please mark any incomplete areas of The Guide with a `todo directive
 <http://sphinx.pocoo.org/ext/todo.html?highlight=todo#directive-todo>`_. To
@@ -5,8 +5,10 @@ Systems Administration

 .. image:: /_static/photos/34435690580_3afec7d4cd_k_d.jpg

+
+******
 Fabric
------
+******

 `Fabric <http://docs.fabfile.org>`_ is a library for simplifying system
 administration tasks. While Chef and Puppet tend to focus on managing servers
@@ -73,8 +75,10 @@ programs, and host grouping.

    `Fabric Documentation <http://docs.fabfile.org>`_

+
+****
 Salt
----
+****

 `Salt <http://saltstack.org/>`_ is an open source infrastructure management
 tool.  It supports remote command execution from a central point (master host)
@@ -132,8 +136,9 @@ State files can be written using YAML, the Jinja2 template system or pure Python
    `Salt Documentation <http://docs.saltstack.com>`_


+******
 Psutil
------
+******

 `Psutil <https://github.com/giampaolo/psutil/>`_ is an interface to different
 system information (e.g. CPU, memory, disks, network, users and processes).
@@ -188,8 +193,10 @@ A full terminal application like a widely extended top which is based on
 psutil and with the ability of a client-server monitoring is
 `glance <https://github.com/nicolargo/glances/>`_.

+
+*******
 Ansible
-------
+*******

 `Ansible <http://ansible.com/>`_  is an open source system automation tool.
 The biggest advantage over Puppet or Chef is it does not require an agent on
@@ -240,8 +247,10 @@ about Ansible, read the `Ansible Docs <http://docs.ansible.com/>`_.
 great and detailed introduction to getting started with Ansible.


+****
 Chef
----
+****
+
 `Chef <https://www.chef.io/chef/>`_  is a systems and cloud infrastructure automation
 framework that makes it easy to deploy servers and applications to any physical,
 virtual, or cloud location. In case this is your choice for configuration management,
@@ -271,8 +280,10 @@ found on the `Chef Supermarket <https://supermarket.chef.io/cookbooks>`_.

 - `Chef Documentation <https://docs.chef.io/>`_

+
+******
 Puppet
------
+******

 `Puppet <http://puppetlabs.com>`_ is IT Automation and configuration management
 software from Puppet Labs that allows System Administrators to define the state
@@ -367,13 +378,17 @@ everytime the sshd configuration file is changed.

 For more information, refer to the `Puppet Labs Documentation <http://docs.puppetlabs.com>`_

+
+*********
 Blueprint
---------
+*********

 .. todo:: Write about Blueprint

+
+********
 Buildout
--------
+********

 `Buildout <http://www.buildout.org>`_ is an open source software build tool.
 Buildout is created using the Python programming language. It implements a
@@ -382,8 +397,10 @@ Buildout is primarily used to download and set up dependencies in Python eggs
 format of the software being developed or deployed. Recipes for build tasks in any
 environment can be created, and many are already available.

+
+*******
 Shinken
-------
+*******

 `Shinken <http://www.shinken-monitoring.org/>`_ is a modern, Nagios compatible
 monitoring framework written in Python. Its main goal is to give users a flexible
@@ -8,8 +8,10 @@ Continuous Integration
 .. note::
    For advice on writing your tests, see :doc:`/writing/tests`.

+
+****
 Why?
----
+****

 Martin Fowler, who first wrote about `Continuous Integration <http://martinfowler.com/articles/continuousIntegration.html>`_
 (short: CI) together with Kent Beck, describes the CI as follows:
@@ -22,24 +24,26 @@ Martin Fowler, who first wrote about `Continuous Integration <http://martinfowle
    significantly reduced integration problems and allows a team to develop
    cohesive software more rapidly.

+
+*******
 Jenkins
-------
+*******

 `Jenkins CI <http://jenkins-ci.org>`_ is an extensible continuous integration
 engine. Use it.


-
+********
 Buildbot
--------
+********

 `Buildbot <http://docs.buildbot.net/current/>`_ is a Python system to
 automate the compile/test cycle to validate code changes.


-
+***
 Tox
---
+***

 `tox <https://tox.readthedocs.io/en/latest/>`_ is an automation tool providing
 packaging, testing and deployment of Python software right from the console or
@@ -54,8 +58,9 @@ which provides the following features:
  and merging CI and shell-based testing.


+*********
 Travis-CI
---------
+*********

 `Travis-CI <https://travis-ci.org/>`_ is a distributed CI server which builds
 tests for open source projects for free. It provides multiple workers to run
@@ -23,31 +23,39 @@ Some popular command-line applications include:
 * `mercurial <https://www.mercurial-scm.org/>`_ - A distributed version control
  system primarily written in Python

+
+*****
 Clint
-----
+*****

 `clint <https://pypi.python.org/pypi/clint/>`_ is a Python module which is
 filled with very useful tools for developing command-line applications.
 It supports features such as; CLI colors and indents, simple and powerful
 column printer, iterator based progress bars and implicit argument handling.

+
+*****
 Click
-----
+*****

 `click <http://click.pocoo.org/>`_ is a Python package for creating
 command-line interfaces in a composable way with as little code as
 possible. This “Command-line Interface Creation Kit” is highly
 configurable but comes with good defaults out of the box.

+
+******
 docopt
------
+******

 `docopt <http://docopt.org/>`_ is a lightweight, highly Pythonic package that
 allows creating command-line interfaces easily and intuitively, by parsing
 POSIX-style usage instructions.

+
+****
 Plac
------
+****

 `Plac <https://pypi.python.org/pypi/plac>`_ is a simple wrapper
 over the Python standard library `argparse <http://docs.python.org/2/library/argparse.html>`_,
@@ -57,8 +65,10 @@ module targets especially unsophisticated users, programmers, sys-admins,
 scientists and in general people writing throw-away scripts for themselves,
 who choose to create a command-line interface because it is quick and simple.

+
+*****
 Cliff
------
+*****

 `Cliff <http://docs.openstack.org/developer/cliff/>`_  is a framework for
 building command-line programs. It uses setuptools entry points to provide
@@ -67,8 +77,10 @@ to be used to create multi-level commands such as subversion and git, where
 the main program handles some basic argument parsing and then invokes a
 sub-command to do the work.

+
+******
 Cement
------
+******

 `Cement <http://builtoncement.com/>`_ is an advanced CLI Application Framework.
 Its goal is to introduce a standard, and feature-full platform
@@ -77,8 +89,10 @@ as support rapid development needs without sacrificing quality.
 Cement is flexible, and it's use cases span from the simplicity of a micro-framework
 to the complexity of a meg-framework.

+
+***********
 Python Fire
-----------
+***********

 `Python Fire <https://github.com/google/python-fire/>`_ is a library for
 automatically generating command line interfaces from absolutely any Python
@@ -5,8 +5,10 @@ Interfacing with C/C++ Libraries

 .. image:: /_static/photos/34725951345_c8f5959a2e_k_d.jpg

+
+****************************
 C Foreign Function Interface
----------------------------
+****************************

 `CFFI <https://cffi.readthedocs.io/en/latest/>`_ provides a simple to use
 mechanism for interfacing with C from both CPython and PyPy. It supports two
@@ -29,8 +31,10 @@ ABI Interaction
    # prints: 23
    print("{}".format(length))

+
+******
 ctypes
------
+******

 `ctypes <https://docs.python.org/3/library/ctypes.html>`_ is the de facto
 library for interfacing with C/C++ from CPython, and it provides not only
@@ -68,8 +72,10 @@ Struct Equivalents
        _fields_ = [("a", c_int),
                    ("b", c_int)]

+
+****
 SWIG
----
+****

 `SWIG <http://www.swig.org>`_, though not strictly Python focused (it supports a
 large number of scripting languages), is a tool for generating bindings for
@@ -124,8 +130,9 @@ Example: Overloading __repr__
    %include "MyClass.h"


+************
 Boost.Python
------------
+************

 `Boost.Python <http://www.boost.org/doc/libs/1_59_0/libs/python/doc/>`_
 requires a bit more manual work to expose C++ object functionality, but
@@ -5,8 +5,10 @@ Network Applications

 .. image:: /_static/photos/34364815780_bea6614025_k_d.jpg

+
+****
 HTTP
-::::
+****

 The Hypertext Transfer Protocol (HTTP) is an application protocol for
 distributed, collaborative, hypermedia information systems. HTTP is the
@@ -31,8 +33,9 @@ Requests.
 - `GitHub <https://github.com/kennethreitz/requests>`_


+*******************
 Distributed Systems
-::::::::::::::::::::
+*******************


 ZeroMQ
@@ -5,8 +5,10 @@ Cryptography

 .. image:: /_static/photos/33907152824_bf91078cc1_k_d.jpg

+
+************
 Cryptography
------------
+************

 `Cryptography <https://cryptography.io/en/latest/>`_ is an actively developed
 library that provides cryptographic recipes and primitives. It supports
@@ -40,10 +42,9 @@ Example code using high level symmetric encryption recipe:
 	plain_text = cipher_suite.decrypt(cipher_text)


-
-
+**************
 GPGME bindings
--------------
+**************

 The `GPGME Python bindings <https://dev.gnupg.org/source/gpgme/browse/master/lang/python/>`_ provide pythonic access to `GPG Made Easy <https://dev.gnupg.org/source/gpgme/browse/master/>`_, a C API for the entire GNU Privacy Guard suite of projects, including GPG, libgcrypt and gpgsm (the S/MIME engine). It supports Python 2.6, 2.7, 3.4 and above. Depends on the SWIG C interface for Python as well as the GnuPG software and libraries.

@@ -52,12 +53,12 @@ A more comprehensive `GPGME Python Bindings HOWTO <https://dev.gnupg.org/source/
 Available under the same terms as the rest of the GnuPG Project: GPLv2 and LGPLv2.1, both with the "or any later version" clause.

 Installation
------------
+~~~~~~~~~~~~

 Included by default when compiling GPGME if the configure script locates a supported python version (which it will if it's in $PATH during configuration).

 Example
-------
+~~~~~~~

 .. code-block:: python3

@@ -90,9 +91,9 @@ Example



-
+********
 PyCrypto
--------
+********

 `PyCrypto <https://www.dlitz.net/software/pycrypto/>`_ is another library,
 which provides secure hash functions and various encryption algorithms. It
@@ -5,8 +5,10 @@ Databases

 .. image:: /_static/photos/33907152464_a99fdcc8de_k_d.jpg

+
+******
 DB-API
------
+******

 The Python Database API (DB-API) defines a standard interface for Python
 database access modules. It's documented in :pep:`249`.
@@ -17,8 +19,10 @@ Tutorials that explain how to work with modules that conform to this interface c
 `here <http://halfcooked.com/presentations/osdc2006/python_databases.html>`__ and
 `here <http://web.archive.org/web/20120815130844/http://www.amk.ca/python/writing/DB-API.html>`__.

+
+**********
 SQLAlchemy
----------
+**********

 `SQLAlchemy <http://www.sqlalchemy.org/>`_ is a commonly used database toolkit.
 Unlike many database libraries it not only provides an ORM layer but also a
@@ -28,8 +32,10 @@ generalized API for writing database-agnostic code without SQL.

    $ pip install sqlalchemy

+
+*******
 Records
-------
+*******

 `Records <https://github.com/kennethreitz/records>`_ is minimalist SQL library,
 designed for sending raw SQL queries to various databases. Data can be used
@@ -41,8 +47,10 @@ programmatically, or exported to a number of useful data formats.

 Also included is a command-line tool for exporting SQL data.

+
+**********
 Django ORM
----------
+**********

 The Django ORM is the interface used by `Django <http://www.djangoproject.com>`_
 to provide database access.
@@ -58,8 +66,10 @@ The basics:
 - Django gives you an automatically-generated database-access API; see
  `Making queries <https://docs.djangoproject.com/en/dev/topics/db/queries/>`__.

+
+******
 peewee
------
+******

 `peewee <http://docs.peewee-orm.com/en/latest/>`_ is another ORM with a focus
 on being lightweight with support for Python 2.6+ and 3.2+ which supports
@@ -71,8 +81,10 @@ to query data. While SQLite, MySQL and Postgres are supported out-of-the-box,
 there is a `collection of add-ons <https://peewee.readthedocs.io/en/latest/peewee/playhouse.html#playhouse>`_
 available.

+
+*******
 PonyORM
-------
+*******

 `PonyORM <http://ponyorm.com/>`_ is an ORM that takes a different approach to
 querying the database. Instead of writing an SQL-like language or boolean
@@ -81,9 +93,9 @@ schema editor that can generate PonyORM entities for you. It supports Python
 2.6+ and Python 3.3+ and can connect to SQLite, MySQL, Postgres & Oracle


-
+*********
 SQLObject
---------
+*********

 `SQLObject <http://www.sqlobject.org/>`_ is yet another ORM. It supports a wide
 variety of databases: Common database systems MySQL, Postgres and SQLite and
@@ -8,8 +8,11 @@ GUI Applications

 Alphabetical list of GUI Applications.

+
+*******
 Camelot
-------
+*******
+
 `Camelot <http://www.python-camelot.com>`_ provides components for building
 applications on top of Python, SQLAlchemy and Qt.  It is inspired by
 the Django admin interface.
@@ -18,27 +21,39 @@ The main resource for information is the website:
 http://www.python-camelot.com
 and the mailing list https://groups.google.com/forum/#!forum/project-camelot

+
+*****
 Cocoa
-----
+*****
+
 .. note:: The Cocoa framework is only available on OS X. Don't pick this if you're writing a cross-platform application!

+
+***
 GTk
---
+***
+
 PyGTK provides Python bindings for the GTK+ toolkit. Like the GTK+ library
 itself, it is currently licensed under the GNU LGPL. It is worth noting that
 PyGTK only currently supports the Gtk-2.X API (NOT Gtk-3.0). It is currently
 recommended that PyGTK not be used for new projects and that existing
 applications be ported from PyGTK to PyGObject.

+
+********************
 PyGObject aka (PyGi)
--------------------
+********************
+
 `PyGObject <https://wiki.gnome.org/Projects/PyGObject>`_ provides Python bindings, which gives access to the entire GNOME software platform.
 It is fully compatible with GTK+ 3. Here is a tutorial to get started with `Python GTK+ 3 Tutorial <https://python-gtk-3-tutorial.readthedocs.io/en/latest/>`_.

 `API Reference <http://lazka.github.io/pgi-docs/>`_

+
+****
 Kivy
----
+****
+
 `Kivy <http://kivy.org>`_ is a Python library for development of multi-touch
 enabled media rich applications. The aim is to allow for quick and easy
 interaction design and rapid prototyping, while making your code reusable
@@ -53,12 +68,18 @@ on all major platforms (Linux, OSX, Windows, Android).

 The main resource for information is the website: http://kivy.org

+
+******
 PyObjC
------
+******
+
 .. note:: Only available on OS X. Don't pick this if you're writing a cross-platform application.

+
+******
 PySide
------
+******
+
 PySide is a Python binding of the cross-platform GUI toolkit Qt.

 .. code-block:: console
@@ -67,16 +88,22 @@ PySide is a Python binding of the cross-platform GUI toolkit Qt.

 https://wiki.qt.io/Category:LanguageBindings::PySide::Downloads

+
+****
 PyQt
----
+****
+
 .. note:: If your software does not fully comply with the GPL you will need a commercial license!

 PyQt provides Python bindings for the Qt Framework (see below).

 http://www.riverbankcomputing.co.uk/software/pyqt/download

+
+*****************************
 PyjamasDesktop (pyjs Desktop)
-----------------------------
+*****************************
+
 PyjamasDesktop is a port of Pyjamas. PyjamasDesktop is application widget set
 for desktop and a cross-platform framework. (After release v0.6 PyjamasDesktop
 is a part of Pyjamas (Pyjs)). Briefly, it allows the exact same Python web
@@ -86,14 +113,20 @@ application source code to be executed as a standalone desktop application.

 The main website; `pyjs Desktop <http://pyjs.org/>`_.

+
+**
 Qt
--
+**
+
 `Qt <http://qt-project.org/>`_ is a cross-platform application framework that
 is widely used for developing software with a GUI but can also be used for
 non-GUI applications.

+
+***********
 PySimpleGUI 
------  
+***********
+
 `PySimpleGUI <https://pysimplegui.readthedocs.io/>`_ is a  wrapper for Tkinter and Qt (others on the way).  The amount of code required to implement custom GUIs is much shorter using PySimpleGUI than if the same GUI were written directly using tkinter or Qt.  PySimpleGUI code can be "ported" between GUI frameworks by changing import statement.

 .. code-block:: console 
@@ -102,8 +135,11 @@ PySimpleGUI

 PySimpleGUI is contained in a single PySimpleGUI.py file.  Should pip installation be impossible, pasting the PySimpleGUI.py file into a project's folder is all that's required to import and begin using.

+
+****
 Toga
----
+****
+
 `Toga <https://toga.readthedocs.io/en/latest/>`_ is a Python native, OS
 native, cross platform GUI toolkit. Toga consists of a library of base
 components with a shared interface to simplify platform-agnostic GUI
@@ -112,8 +148,11 @@ development.
 Toga is available on Mac OS, Windows, Linux (GTK), and mobile platforms such
 as Android and iOS.

+
+**
 Tk
--
+**
+
 Tkinter is a thin object-oriented layer on top of Tcl/Tk. **It has the advantage
 of being included with the Python standard library, making it the most
 convenient and compatible toolkit to program with.**
@@ -126,8 +165,11 @@ There's a good multi-language Tk tutorial with Python examples at
 `TkDocs <http://www.tkdocs.com/tutorial/index.html>`_. There's more information
 available on the `Python Wiki <http://wiki.python.org/moin/TkInter>`_.

+
+********
 wxPython
--------
+********
+
 wxPython is a GUI toolkit for the Python programming language. It allows
 Python programmers to create programs with a robust, highly functional
 graphical user interface, simply and easily. It is implemented as a Python
@@ -11,8 +11,10 @@ Computer Vision (OpenCV).

 A brief description of both is given below.

+
+**********************
 Python Imaging Library
----------------------
+**********************

 The `Python Imaging Library <http://www.pythonware.com/products/pil/>`_, or PIL
 for short, is one of the core libraries for image manipulation in Python. Unfortunately,
@@ -63,8 +65,9 @@ There are more examples of the Pillow library in the
 `Pillow tutorial <https://pillow.readthedocs.io/en/3.0.x/handbook/tutorial.html>`_.


+**************************
 OpenSource Computer Vision
--------------------------
+**************************

 OpenSource Computer Vision, more commonly known as OpenCV, is a more advanced
 image manipulation and processing software than PIL. It has been implemented
@@ -9,8 +9,10 @@ The `json <https://docs.python.org/2/library/json.html>`_ library can parse
 JSON from strings or files. The library parses JSON into a Python dictionary
 or list. It can also convert Python dictionaries or lists into JSON strings.

+
+************
 Parsing JSON
------------
+************

 Take the following string containing JSON data:

@@ -46,8 +48,9 @@ You can also convert the following to JSON:
    '{"first_name": "Guido", "last_name": "Rossum", "titles": ["BDFL", "Developer"]}'


+**********
 simplejson
----------
+**********

 The JSON library was added to Python in version 2.6.
 If you're using an earlier version of Python, the
@@ -10,8 +10,10 @@ Python has a vast number of libraries for data analysis, statistics and Machine

 Some widely used packages for Machine Learning and other Data Science applications are enlisted below.

+
+***********
 Scipy Stack
-----------
+***********

 The Scipy stack consists of a bunch of core helper packages used in data science, for statistical analysis and visualising data. Because of its huge number of functionalities and ease of use, the Stack is considered a must-have for most data science applications.

@@ -34,8 +36,10 @@ For installing the full stack, or individual packages, you can refer to the inst

 **NB:** `Anaconda <https://www.continuum.io/anaconda-overview>`_ is highly preferred and recommended for installing and maintaining data science packages seamlessly.

+
+************
 scikit-learn
------------
+************

 Scikit is a free and open-source machine learning library for Python. It offers off-the-shelf functions to implement many algorithms like linear regression, classifiers, SVMs, k-means, Neural Networks etc. It also has a few sample datasets which can be directly used for training and testing.

@@ -5,8 +5,10 @@ Networking

 .. image:: /_static/photos/34151833832_6bdfd930af_k_d.jpg

+
+*******
 Twisted
-------
+*******

 `Twisted <http://twistedmatrix.com/trac/>`_ is an event-driven networking
 engine. It can be used to build applications around many different networking
@@ -14,8 +16,10 @@ protocols, including http servers and clients, applications using SMTP, POP3,
 IMAP or SSH protocols, instant messaging
 and `much more <http://twistedmatrix.com/trac/wiki/Documentation>`_.

+
+*****
 PyZMQ
-----
+*****

 `PyZMQ <http://zeromq.github.com/pyzmq/>`_ is the Python binding for
 `ZeroMQ <http://www.zeromq.org/>`_, which is a high-performance asynchronous
@@ -32,8 +36,10 @@ message queuing without a message broker. The basic patterns for this are:

 For a quick start, read the `ZeroMQ guide <http://zguide.zeromq.org/page:all>`_.

+
+******
 gevent
------
+******

 `gevent <http://www.gevent.org/>`_ is a coroutine-based Python networking
 library that uses greenlets to provide a high-level synchronous API on top of
@@ -5,8 +5,10 @@ Scientific Applications

 .. image:: /_static/photos/33925223870_97e44f5629_k_d.jpg

+
+*******
 Context
-:::::::
+*******

 Python is frequently used for high-performance scientific applications. It
 is widely used in academia and scientific projects because it is easy to write
@@ -21,8 +23,9 @@ Python ecosystem can be found in the `Python Scientific Lecture Notes
 <http://scipy-lectures.github.com/>`_


+*****
 Tools
-:::::
+*****

 IPython
 -------
@@ -37,8 +40,9 @@ store chunks of Python code along side the results and additional comments
 file formats.


+*********
 Libraries
-:::::::::
+*********

 NumPy
 -----
@@ -112,8 +116,9 @@ The library handles presentation of stimuli, scripting of experimental design
 and data collection.


+*********
 Resources
-:::::::::
+*********

 Installation of scientific Python packages can be troublesome, as many of
 these packages are implemented as Python C extensions which need to be compiled.
@@ -5,8 +5,10 @@ HTML Scraping

 .. image:: /_static/photos/34268661876_442428e122_k_d.jpg

+
+************
 Web Scraping
------------
+************

 Web sites are written using HTML, which means that each web page is a
 structured document. Sometimes it would be great to obtain some data from
@@ -18,8 +20,10 @@ computer program to sift through a web page and gather the data that you need
 in a format most useful to you while at the same time preserving the structure
 of the data.

+
+*****************
 lxml and Requests
-----------------
+*****************

 `lxml <http://lxml.de/>`_ is a pretty extensive library written for parsing
 XML and HTML documents very quickly, even handling messed up tags in the
@@ -5,8 +5,10 @@ Data Serialization

 .. image:: /_static/photos/33467946364_3e59bd376a_k_d.jpg

+
+***************************
 What is data serialization?
---------------------------
+***************************

 Data serialization is the concept of converting structured data into a format
 that allows it to be shared or stored in such a way that its original
@@ -14,8 +16,10 @@ structure to be recovered. In some cases, the secondary intention of data
 serialization is to minimize the size of the serialized data which then
 minimizes disk space or bandwidth requirements.

+
+******
 Pickle
------
+******

 The native data serialization module for Python is called `Pickle
 <https://docs.python.org/2/library/pickle.html>`_.
@@ -35,8 +39,10 @@ Here's an example:
        #Use loads to de-serialize an object
        received_grades = pickle.loads( serial_grades )

+
+********
 Protobuf
--------
+********

 If you're looking for a serialization module that has support in multiple
 languages, Google's `Protobuf
@@ -37,8 +37,10 @@ and PyPy's processing.
   1.54693889618
   1.60109114647

+
+*******
 Context
-:::::::
+*******


 The GIL
@@ -65,8 +67,10 @@ The GIL
 `Special care`_ must be taken when writing C extensions to make sure you
 register your threads with the interpreter.

+
+************
 C Extensions
-::::::::::::
+************


 Cython
@@ -226,8 +230,10 @@ Pyrex
 Shedskin?
 ---------

+
+***********
 Concurrency
-:::::::::::
+***********


 Concurrent.futures
@@ -9,8 +9,10 @@ As a powerful scripting language adapted to both fast prototyping
 and bigger projects, Python is widely used in web application
 development.

+
+*******
 Context
-:::::::
+*******



@@ -25,8 +27,9 @@ can be deployed in any :ref:`WSGI-compliant web server <wsgi-servers-ref>`.
 WSGI is documented in :pep:`3333`.


+**********
 Frameworks
-::::::::::
+**********

 Broadly speaking, a web framework consists of a set of libraries and a main
 handler within which you can build custom code to implement a web application
@@ -141,8 +144,10 @@ Masonite comes with a lot of functionality out of the box including a powerful I

 Masonite is perfect for beginners or experienced developers alike and works hard to be fast and easy from install through to deployment. Try it once and you’ll fall in love.

+
+***********
 Web Servers
-:::::::::::
+***********

 .. _nginx-ref:

@@ -159,8 +164,10 @@ to serve high-load websites, Nginx is gradually becoming quite popular.

 .. _wsgi-servers-ref:

+
+************
 WSGI Servers
-::::::::::::
+************

 Stand-alone WSGI servers typically use less resources than traditional web
 servers and provide top performance [3]_.
@@ -215,8 +222,9 @@ I do not recommend using uWSGI unless you know why you need it.
 .. _server-best-practices-ref:


+*********************
 Server Best Practices
-:::::::::::::::::::::
+*********************

 The majority of self-hosted Python applications today are hosted with a WSGI
 server such as :ref:`Gunicorn <gunicorn-ref>`, either directly or behind a
@@ -226,8 +234,10 @@ The WSGI servers serve the Python applications while the web server handles
 tasks better suited for it such as static file serving, request routing, DDoS
 protection, and basic authentication.

+
+*******
 Hosting
-:::::::
+*******

 Platform-as-a-Service (PaaS) is a type of cloud computing infrastructure
 which abstracts and manages infrastructure, routing, and scaling of web
@@ -259,8 +269,10 @@ Eldarion
 by Kubernetes, CoreOS, and Docker. They support any WSGI application and have a
 guide on deploying `Django projects <https://eldarion-gondor.github.io/docs/how-to/setup-deploy-first-django-project/>`_.

+
+**********
 Templating
-::::::::::
+**********

 Most WSGI applications are responding to HTTP requests to serve content in HTML
 or other markup languages. Instead of generating directly textual content from
@@ -5,8 +5,10 @@ XML parsing

 .. image:: /_static/photos/33888714601_a1f7d020a2_k_d.jpg

+
+********
 untangle
--------
+********

 `untangle <https://github.com/stchris/untangle>`_ is a simple library which
 takes an XML document and returns a Python object which mirrors the nodes and
@@ -36,8 +38,10 @@ and then you can get the child elements name like this:

 untangle also supports loading XML from a string or an URL.

+
+*********
 xmltodict
---------
+*********

 `xmltodict <http://github.com/martinblech/xmltodict>`_ is another simple
 library that aims at making XML feel like working with JSON.
@@ -27,8 +27,10 @@ distribution by about 2–12MB. Also, you will be responsible for shipping
 updated versions of your application when security vulnerabilities to
 Python are patched.

+
+************************
 Alternatives to Freezing
------------------------
+************************

 :ref:`Packaging your code <packaging-your-code-ref>` is for distributing
 libraries or tools to other developers.
@@ -40,8 +42,9 @@ On Linux, an alternative to freezing is to
 .. todo:: Fill in "Freezing Your Code" stub


+****************************
 Comparison of Freezing Tools
----------------------------
+****************************

 Solutions and platforms/features supported:

@@ -65,8 +68,10 @@ py2app      no      no    yes  yes      MIT     no            yes            yes
    Only Pyinstaller makes self-executable exe that bundles the dll when
    passing ``--onefile`` to :file:`Configure.py`.

+
+*******
 Windows
-------
+*******

 bbFreeze
 ~~~~~~~~
@@ -153,8 +158,9 @@ Prerequisite is to have installed :ref:`Python, Setuptools and pywin32 dependenc
 - `Manual <https://pyinstaller.readthedocs.io/en/stable/>`_


+****
 OS X
----
+****


 py2app
@@ -208,8 +214,9 @@ This creates a :code:`script.app` in the :code:`dist` folder. Make sure to use G
 There are several options in :code:`script.spec` related to Mac OS X app bundles `here <http://pythonhosted.org/PyInstaller/spec-files.html#spec-file-options-for-a-mac-os-x-bundle>`_. For example, to specify an icon for the app, use the :code:`icon=\path\to\icon.icns` option.


+*****
 Linux
-----
+*****


 bbFreeze
@@ -31,8 +31,10 @@ makes this method unsuitable for distributing applications to end-users.
 The `Python Packaging Guide <https://python-packaging-user-guide.readthedocs.io/>`_
 provides an extensive guide on creating and maintaining Python packages.

+
+*************************
 Alternatives to Packaging
-:::::::::::::::::::::::::
+*************************

 To distribute applications to end-users, you should
 :ref:`freeze your application <freezing-your-code-ref>`.
@@ -41,8 +43,10 @@ On Linux, you may also want to consider
 :ref:`creating a Linux distro package <packaging-for-linux-distributions-ref>`
 (e.g. a .deb file for Debian or Ubuntu.)

+
+*********************
 For Python Developers
-:::::::::::::::::::::
+*********************

 If you're writing an open source Python module, `PyPI <http://pypi.python.org>`_
 , more properly known as *The Cheeseshop*, is the place to host it.
@@ -141,8 +145,10 @@ prerequisite for this is that you have an Amazon AWS account with an S3 bucket.

 .. _packaging-for-linux-distributions-ref:

+
+***********************
 For Linux Distributions
-::::::::::::::::::::::::
+***********************

 Creating a Linux distro package is arguably the "right way" to distribute code
 on Linux.
@@ -33,8 +33,10 @@ described in the next section before you start building Python applications
 for real-world use. In particular, you should always install Setuptools and pip, as
 it makes it much easier for you to use other third-party Python libraries.

+
+****************
 Setuptools & Pip
----------------
+****************

 The two most crucial third-party Python packages are `setuptools <https://pypi.python.org/pypi/setuptools>`_ and `pip <https://pip.pypa.io/en/stable/>`_.

@@ -53,8 +55,10 @@ To see if pip is installed, open a command prompt and run

 To install pip, `follow the official pip installation guide <https://pip.pypa.io/en/latest/installing/>`_ - this will automatically install the latest version of setuptools.

+
+********************
 Virtual Environments
--------------------
+********************

 A Virtual Environment is a tool to keep the dependencies required by different projects
 in separate places, by creating virtual Python environments for them. It solves the
@@ -23,8 +23,10 @@ good for development. The version shipped with OS X may be out of date from the
 `official current Python release <https://www.python.org/downloads/mac-osx/>`_,
 which is considered the stable production version.

+
+**************
 Doing it Right
--------------
+**************

 Let's install a real version of Python.

@@ -89,8 +91,9 @@ Homebrew names the executable ``python2`` so that you can still run the system P
    $ python3 -V  # Homebrew installed Python 3 interpreter (if installed)


+****************
 Setuptools & Pip
----------------
+****************

 Homebrew installs Setuptools and ``pip`` for you.

@@ -110,9 +113,9 @@ and is actively maintained.
    $ pip -V  # pip pointing to the Homebrew installed Python 3 interpreter (if installed)


-
+********************
 Virtual Environments
--------------------
+********************

 A Virtual Environment (commonly referred to as a 'virtualenv') is a tool to keep the dependencies required by different projects
 in separate places, by creating virtual Python environments for them. It solves the
@@ -52,8 +52,10 @@ described in the next section before you start building Python applications for
 real-world use. In particular, you should always install Setuptools, as it
 makes it much easier for you to use other third-party Python libraries.

+
+****************
 Setuptools + Pip
----------------
+****************

 The two most crucial third-party Python packages are `setuptools <https://pypi.python.org/pypi/setuptools>`_ and `pip <https://pip.pypa.io/en/stable/>`_.

@@ -73,8 +75,9 @@ To see if pip is installed, open a command prompt and run
 To install pip, `follow the official pip installation guide <https://pip.pypa.io/en/latest/installing/>`_ - this will automatically install the latest version of setuptools.


+********************
 Virtual Environments
--------------------
+********************

 A Virtual Environment is a tool to keep the dependencies required by different projects
 in separate places, by creating virtual Python environments for them. It solves the
@@ -1,7 +1,9 @@
 .. _install3-linux:

+
+############################
 Installing Python 3 on Linux
-============================
+############################

 .. image:: /_static/photos/34435689480_2e6f358510_k_d.jpg

@@ -42,8 +44,9 @@ to read about `multiple Python versions available in Fedora`_.
 .. _multiple Python versions available in Fedora: https://developer.fedoraproject.org/tech/languages/python/multiple-pythons.html


+*********************
 Working with Python 3
---------------------
+*********************

 At this point, you may have system Python 2.7 available as well.

@@ -59,8 +62,10 @@ This will launch the Python 2 interpreter.

 This will launch the Python 3 interpreter.

+
+****************
 Setuptools & Pip
----------------
+****************

 The two most crucial third-party Python packages are `setuptools <https://pypi.python.org/pypi/setuptools>`_ and `pip <https://pip.pypa.io/en/stable/>`_.

@@ -90,8 +95,9 @@ However, when using virtual environments (described below), you don't need to
 care about that.


+*****************************
 Pipenv & Virtual Environments
-----------------------------
+*****************************

 The next step is to install Pipenv, so you can install dependencies and manage virtual environments.

@@ -2,8 +2,10 @@

 .. _install3-osx:

+
+###############################
 Installing Python 3 on Mac OS X
-===============================
+###############################

 .. image:: /_static/photos/34435689480_2e6f358510_k_d.jpg

@@ -17,8 +19,10 @@ good for development. The version shipped with OS X may be out of date from the
 `official current Python release <https://www.python.org/downloads/mac-osx/>`_,
 which is considered the stable production version.

+
+**************
 Doing it Right
--------------
+**************

 Let's install a real version of Python.

@@ -72,14 +76,16 @@ Now, we can install Python 3:

 This will take a minute or two.

-
+***
 Pip
---
+***

 Homebrew installs ``pip`` pointing to the Homebrew'd Python 3 for you.

+
+*********************
 Working with Python 3
---------------------
+*********************

 At this point, you have the system Python 2.7 available, potentially the
 :ref:`Homebrew version of Python 2 <install-osx>` installed, and the Homebrew
@@ -115,8 +121,9 @@ The rest of the guide will assume that ``python`` references Python 3.
    Python 3.7.1 # Success!


+*****************************
 Pipenv & Virtual Environments
-----------------------------
+*****************************

 The next step is to install Pipenv, so you can install dependencies and manage virtual environments.

@@ -1,7 +1,9 @@
 .. _install3-windows:

+
+##############################
 Installing Python 3 on Windows
-==============================
+##############################

 .. image:: /_static/photos/34435689480_2e6f358510_k_d.jpg

@@ -17,8 +19,10 @@ Once done, installing Python 3 is very simple, because Chocolatey pushes Python
 Once you've run this command, you should be able to launch Python directly from to the console.
 (Chocolatey is fantastic and automatically adds Python to your path.)

+
+****************
 Setuptools + Pip
----------------
+****************

 The two most crucial third-party Python packages are `setuptools <https://pypi.python.org/pypi/setuptools>`_ and `pip <https://pip.pypa.io/en/stable/>`_,
 which let you download, install and uninstall any compliant Python software
@@ -30,8 +34,9 @@ All supported versions of Python 3 include pip, so just make sure it's up to dat
    python -m pip install -U pip


+*****************************
 Pipenv & Virtual Environments
-----------------------------
+*****************************

 The next step is to install Pipenv, so you can install dependencies and manage virtual environments.

@@ -19,9 +19,9 @@ other third-party Python libraries.
 .. 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.
  —*Kenneth Reitz*

-
+*******************
 Installation Guides
-------------------
+*******************

 These guides go over the proper installation of :ref:`Python <which-python>`
 for development purposes, as well as setuptools, pip and virtualenv.
@@ -8,8 +8,10 @@ Picking a Python Interpreter (3 vs 2)

 .. _which-python:

+
+***************************
 The State of Python (3 & 2)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+***************************

 When choosing a Python interpreter, one looming question is always present:
 "Should I choose Python 2 or Python 3"? The answer is a bit more subtle than
@@ -23,8 +25,10 @@ The basic gist of the state of things is as follows:
 3. Python 2.7 will only receive necessary security updates until 2020 [#pep373_eol]_.
 4. The brand name "Python" encapsulates both Python 3 and Python 2.

+
+***************
 Recommendations
-~~~~~~~~~~~~~~~
+***************


 .. 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.
@@ -41,8 +45,10 @@ I'll be blunt:
  simultaneously. Only supporting Python 3 for a new library you want to be widely adopted is a
  political statement and will alienate many of your users. This is not a problem — slowly, over the next three years, this will become less the case.

+
+*********
 So.... 3?
-~~~~~~~~~
+*********

 If you're choosing a Python interpreter to use, I
 recommend you use the newest Python 3.x, since every version brings new and
@@ -65,8 +71,10 @@ worry about.  Note that Python 2.6 is end-of-life upstream, so you shouldn't
 try to write 2.6-compatible code unless you're being paid specifically to
 do that.

+
+***************
 Implementations
-~~~~~~~~~~~~~~~
+***************

 When people speak of *Python* they often mean not just the language but also
 the CPython implementation. *Python* is actually a specification for a language
@@ -1,5 +1,8 @@
+
+
+#############
 Documentation
-=============
+#############

 .. image:: /_static/photos/35620636012_f66aa88f93_k_d.jpg

@@ -7,8 +10,10 @@ Readability is a primary focus for Python developers, in both project
 and code documentation. Following some simple best practices can save
 both you and others a lot of time.

+
+*********************
 Project Documentation
---------------------
+*********************

 A :file:`README` file at the root directory should give general information
 to both users and maintainers of a project. It should be raw text or
@@ -32,8 +37,10 @@ planned development for the code.
 A :file:`CHANGELOG` file or section in :file:`README` should compile a short
 overview of the changes in the code base for the latest versions.

+
+*******************
 Project Publication
-------------------
+*******************

 Depending on the project, your documentation might include some or all
 of the following components:
@@ -97,8 +104,9 @@ Reference`_ should help you familiarize yourself with its syntax.
 .. _reStructuredText Quick Reference: http://docutils.sourceforge.net/docs/user/rst/quickref.html


+*************************
 Code Documentation Advice
-------------------------
+*************************

 Comments clarify the code and they are added with purpose of making the
 code easier to understand. In Python, comments begin with a hash
@@ -249,8 +257,10 @@ For further reading on docstrings, feel free to consult :pep:`257`
 .. _sphinx.ext.napoleon: https://sphinxcontrib-napoleon.readthedocs.io/
 .. _`NumPy style`: http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html

+
+***********
 Other Tools
-----------
+***********

 You might see these in the wild. Use :ref:`sphinx-ref`.

@@ -1,5 +1,8 @@
+
+
+##############
 Common Gotchas
-==============
+##############

 .. image:: /_static/photos/34435688380_b5a740762b_k_d.jpg

@@ -16,8 +19,10 @@ the surprise.

 .. _default_args:

+
+*************************
 Mutable Default Arguments
-------------------------
+*************************

 Seemingly the *most* common surprise new Python programmers encounter is
 Python's treatment of mutable default arguments in function definitions.
@@ -88,8 +93,9 @@ to maintain state between calls of a function. This is often done when writing
 a caching function.


+****************************
 Late Binding Closures
---------------------
+****************************

 Another common source of confusion is the way Python binds its variables in
 closures (or in the surrounding global scope).
@@ -189,9 +195,9 @@ lots of situations. Looping to create unique functions is unfortunately a case
 where they can cause hiccups.


-
+*********************************
 Bytecode (.pyc) Files Everywhere!
---------------------------------
+*********************************

 By default, when executing Python code from files, the Python interpreter
 will automatically write a bytecode version of that file to disk, e.g.
@@ -1,5 +1,8 @@
+
+
+##################
 Choosing a License
-==================
+##################

 .. image:: /_static/photos/33907149294_82d7535a6c_k_d.jpg

@@ -1,5 +1,8 @@
+
+
+#######
 Logging
-=======
+#######

 .. image:: /_static/photos/35254379756_c9fe23f843_k_d.jpg

@@ -17,8 +20,9 @@ Logging serves two purposes:
  reports or to optimize a business goal.


+*************
 ... or Print?
-------------
+*************

 The only time that ``print`` is a better option than logging is when
 the goal is to display a help statement for a command line application.
@@ -34,8 +38,9 @@ Other reasons why logging is better than ``print``:
  :attr:`logging.Logger.disabled` to ``True``.


+********************
 Logging in a Library
--------------------
+********************

 Notes for `configuring logging for a library`_ are in the
 `logging tutorial`_.  Because the *user*, not the library, should
@@ -61,8 +66,9 @@ this in your ``__init__.py``
    logging.getLogger(__name__).addHandler(logging.NullHandler())


+*************************
 Logging in an Application
-------------------------
+*************************

 The `twelve factor app <http://12factor.net>`_, an authoritative reference
 for good practice in application development, contains a section on
@@ -1,5 +1,8 @@
+
+
+##################
 Reading Great Code
-==================
+##################

 .. image:: /_static/photos/34689452831_93d7fd0571_k_d.jpg

@@ -1,5 +1,8 @@
+
+
+########################
 Structuring Your Project
-========================
+########################

 .. image:: /_static/photos/33907151224_0574e7dfc2_k_d.jpg

@@ -21,9 +24,9 @@ project. We then discuss various perspectives on how to build code which
 can be extended and tested reliably.


-
+***************************
 Structure of the Repository
---------------------------
+***************************

 It's Important.
 :::::::::::::::
@@ -313,9 +316,9 @@ The resulting structure:



-
+************************
 Structure of Code is Key
------------------------
+************************

 Thanks to the way imports and modules are handled in Python, it is
 relatively easy to structure a Python project. Easy, here, means
@@ -366,8 +369,9 @@ include:
  task at hand, you might be swimming in ravioli code.


+*******
 Modules
-------
+*******

 Python modules are one of the main abstraction layers available and probably the
 most natural one. Abstraction layers allow separating code into parts holding
@@ -476,8 +480,9 @@ Being able to tell immediately where a class or function comes from, as in the
 all but the simplest single file projects.


+********
 Packages
--------
+********

 Python provides a very straightforward packaging system, which is simply an
 extension of the module mechanism to a directory.
@@ -509,8 +514,10 @@ Lastly, a convenient syntax is available for importing deeply nested packages:
 ``import very.deep.module as mod``. This allows you to use `mod` in place of the
 verbose repetition of ``very.deep.module``.

+
+***************************
 Object-oriented programming
---------------------------
+***************************

 Python is sometimes described as an object-oriented programming language. This
 can be somewhat misleading and needs to be clarified.
@@ -587,8 +594,9 @@ things that are manipulated (windows, buttons, avatars, vehicles) have a
 relatively long life of their own in the computer's memory.


+**********
 Decorators
----------
+**********

 The Python language provides a simple yet powerful syntax called 'decorators'.
 A decorator is a function or a class that wraps (or decorates) a function
@@ -621,8 +629,10 @@ expensive function in a table and use them directly instead of recomputing
 them when they have already been computed. This is clearly not part
 of the function logic.

+
+****************
 Context Managers
----------------
+****************

 A context manager is a Python object that provides extra contextual information
 to an action. This extra information takes the form of running a callable upon
@@ -694,8 +704,10 @@ to decide when to use which. The class approach might be better if there's
 a considerable amount of logic to encapsulate. The function approach
 might be better for situations where we're dealing with a simple action.

+
+**************
 Dynamic typing
--------------
+**************

 Python is dynamically typed, which means that variables do not have a fixed
 type. In fact, in Python, variables are very different from what they are in
@@ -758,8 +770,10 @@ a `final` keyword and it would be against its philosophy anyway. However, it may
 be a good discipline to avoid assigning to a variable more than once, and it
 helps in grasping the concept of mutable and immutable types.

+
+***************************
 Mutable and immutable types
---------------------------
+***************************

 Python has two kinds of built-in or user-defined types.

@@ -873,16 +887,20 @@ like above or in cases where you are adding to an existing string, using
    foobar = '{foo}{bar}'.format(foo=foo, bar=bar) # It is best


+************************
 Vendorizing Dependencies
------------------------
+************************


+
+*******
 Runners
-------
+*******


+***************
 Further Reading
---------------
+***************

 - http://docs.python.org/2/library/
 - http://www.diveintopython.net/toc/index.html
@@ -1,7 +1,9 @@
 .. _code_style:

+
+##########
 Code Style
-==========
+##########

 .. image:: /_static/photos/33907150054_5ee79e8940_k_d.jpg

@@ -21,8 +23,10 @@ what is considered the best (hear: most readable) way.
 On some border cases, no best way has been agreed upon on how to express
 an intent in Python code, but these cases are rare.

+
+****************
 General concepts
----------------
+****************

 Explicit code
 ~~~~~~~~~~~~~
@@ -260,8 +264,10 @@ is needed.
       return x  # One single exit point for the returned value x will help
                 # when maintaining the code.

+
+******
 Idioms
------
+******

 A programming idiom, put simply, is a *way* to write code. The notion of
 programming idioms is discussed amply at `c2 <http://c2.com/cgi/wiki?ProgrammingIdiom>`_
@@ -417,8 +423,9 @@ hashtable will often be greater than the time saved by the improved search
 speed.


+*************
 Zen of Python
-------------
+*************

 Also known as :pep:`20`, the guiding principles for Python's design.

@@ -450,8 +457,10 @@ Also known as :pep:`20`, the guiding principles for Python's design.
 For some examples of good Python style, see `these slides from a Python user
 group <http://artifex.org/~hblanks/talks/2011/pep20_by_example.pdf>`_.

+
+*****
 PEP 8
-----
+*****

 :pep:`8` is the de-facto code style guide for Python. A high quality,
 easy-to-read version of PEP 8 is also available at `pep8.org <http://pep8.org/>`_.
@@ -504,8 +513,10 @@ Excluding the ``--in-place`` flag will cause the program to output the modified
 code directly to the console for review. The ``--aggressive`` flag will perform
 more substantial changes and can be applied multiple times for greater effect.

+
+***********
 Conventions
----------------
+***********

 Here are some conventions you should follow to make your code easier to read.

@@ -1,5 +1,8 @@
+
+
+#################
 Testing Your Code
-=================
+#################

 .. image:: /_static/photos/34435687940_8f73fc1fa6_k_d.jpg

@@ -71,8 +74,11 @@ Some general rules of testing:
  be to add a test to ensure that the new functionality is not already a
  working path that has not been plugged into the interface.

+
+
+**********
 The Basics
-::::::::::
+**********


 Unittest
@@ -136,8 +142,10 @@ When running this module from the command line as in ``python module.py``, the
 doctests will run and complain if anything is not behaving as described in the
 docstrings.

+
+*****
 Tools
-:::::
+*****


 py.test