From 1758ba7434826d800111de604d1f3c4efe19c7d8 Mon Sep 17 00:00:00 2001 From: Darius Bacon Date: Thu, 29 Dec 2011 21:04:10 -0800 Subject: [PATCH 01/51] Fix indent in code examples. --- docs/writing/documentation.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index 7a4757f..094a013 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -39,23 +39,23 @@ PEP 257 is the primary reference for docstrings. (http://www.python.org/dev/peps |One-line docstrings: :: def kos_root(): - """Return the pathname of the KOS root directory.""" - global _kos_root - if _kos_root: return _kos_root - ... + """Return the pathname of the KOS root directory.""" + global _kos_root + if _kos_root: return _kos_root + ... Multi-line docstrings: :: def complex(real=0.0, imag=0.0): - """Form a complex number. + """Form a complex number. - Keyword arguments: - real -- the real part (default 0.0) - imag -- the imaginary part (default 0.0) + Keyword arguments: + real -- the real part (default 0.0) + imag -- the imaginary part (default 0.0) - """ - if imag == 0.0 and real == 0.0: return complex_zero - ... + """ + if imag == 0.0 and real == 0.0: return complex_zero + ... Sphinx ------ From 944d87956a5177fcc9a8243c0032965202bfac0c Mon Sep 17 00:00:00 2001 From: Mike Thornton Date: Thu, 29 Dec 2011 23:31:04 -0600 Subject: [PATCH 02/51] Added homebrew links --- docs/starting/installation.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/starting/installation.rst b/docs/starting/installation.rst index 16ad7e2..f1dcc3e 100644 --- a/docs/starting/installation.rst +++ b/docs/starting/installation.rst @@ -18,9 +18,9 @@ Package Manager While Snow Leopard comes with a large number of UNIX utilities, those familiar with Linux systems will notice one key component missing: a -package manager. Mxcl's *Homebrew* is the answer. +package manager. Mxcl's `Homebrew `_ is the answer. -To install Homebrew, simply run: :: +To `install Homebrew `_, simply run: :: $ ruby -e "$(curl -fsS http://gist.github.com/raw/323731/install_homebrew.rb)" @@ -41,11 +41,10 @@ bugs. *Don't forget to update your environment PATH.* - Building From Source -------------------- - +.. todo:: Write "Building From Source" Distribute & Pip From 5d8691cef4af361270ff02fc689cfc525679b0ef Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 30 Dec 2011 00:35:26 -0500 Subject: [PATCH 03/51] bunk --- docs/starting/installation.rst | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/docs/starting/installation.rst b/docs/starting/installation.rst index 16ad7e2..4b8477c 100644 --- a/docs/starting/installation.rst +++ b/docs/starting/installation.rst @@ -6,13 +6,6 @@ Mac OS X *Or, "Installing Python 2.7 via Homebrew".* -One of the reasons everybody loves Python is the interactive shell. It -basically allows you to execute Python commands in real time and -immediately get results back. Flask itself does not come with an -interactive shell, because it does not require any specific setup upfront, -just import your application and start playing around. - - Package Manager --------------- @@ -142,7 +135,7 @@ While Python has an extensive standard library, the set of packages available fr $ wget http://python-distribute.org/distribute_setup.py $ python distribute_setup.py - $ wget https://raw.github.com/pypa/pip/master/contrib/get-pip.py + $ wget https://raw.github.com/pypa/pip/master/contrib/get-pip.py $ python get-pip.py $ rm get-pip.py distribute_setup.py From 870fd31b8c54c1bef782e1c67842d7a7e6b61434 Mon Sep 17 00:00:00 2001 From: Mike Thornton Date: Thu, 29 Dec 2011 23:38:18 -0600 Subject: [PATCH 04/51] Enabled TODO extension --- TODO.rst | 2 +- docs/conf.py | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/TODO.rst b/TODO.rst index e50140b..61de3a5 100644 --- a/TODO.rst +++ b/TODO.rst @@ -8,4 +8,4 @@ - virtualenv - webdev - \ No newline at end of file +.. todolist:: \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index bbc7e5e..93ebaec 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -25,7 +25,7 @@ sys.path.append(os.path.abspath('_themes')) # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.ifconfig'] +extensions = ['sphinx.ext.ifconfig', 'sphinx.ext.todo'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -258,3 +258,5 @@ epub_copyright = u'2010, Kenneth Reitz' # Allow duplicate toc entries. #epub_tocdup = True + +todo_include_todos = True \ No newline at end of file From 4a3437548399829d3487bc4d36cecae3477fecf9 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 30 Dec 2011 00:40:49 -0500 Subject: [PATCH 05/51] suck in responsive view --- docs/_themes/kr/layout.html | 7 +- docs/_themes/kr/static/flasky.css_t | 152 +++++++++++++++++++++++++++- 2 files changed, 153 insertions(+), 6 deletions(-) diff --git a/docs/_themes/kr/layout.html b/docs/_themes/kr/layout.html index 75e20e6..890d48f 100644 --- a/docs/_themes/kr/layout.html +++ b/docs/_themes/kr/layout.html @@ -2,17 +2,16 @@ {%- block extrahead %} {{ super() }} {% if theme_touch_icon %} - + {% endif %} - + {% endblock %} {%- block relbar2 %}{% endblock %} {%- block footer %}
© Copyright {{ copyright }}.
- + Fork me on GitHub diff --git a/docs/_themes/kr/static/flasky.css_t b/docs/_themes/kr/static/flasky.css_t index a6ca9d8..e539762 100644 --- a/docs/_themes/kr/static/flasky.css_t +++ b/docs/_themes/kr/static/flasky.css_t @@ -91,8 +91,8 @@ div.sphinxsidebarwrapper { } div.sphinxsidebarwrapper p.logo { - padding: 0 0 20px 0; - margin: 0; + padding: 0; + margin: -10px 0 0 -20px; text-align: center; } @@ -387,6 +387,148 @@ a:hover tt { } +@media screen and (max-width: 870px) { + + div.sphinxsidebar { + display: none; + } + + div.document { + width: 100%; + + } + + div.documentwrapper { + margin-left: 0; + margin-top: 0; + margin-right: 0; + margin-bottom: 0; + } + + div.bodywrapper { + margin-top: 0; + margin-right: 0; + margin-bottom: 0; + margin-left: 0; + } + + ul { + margin-left: 0; + } + + .document { + width: auto; + } + + .footer { + width: auto; + } + + .bodywrapper { + margin: 0; + } + + .footer { + width: auto; + } + + .github { + display: none; + } + + + +} + + + +@media screen and (max-width: 875px) { + + body { + margin: 0; + padding: 20px 30px; + } + + div.documentwrapper { + float: none; + background: white; + } + + div.sphinxsidebar { + display: block; + float: none; + width: 102.5%; + margin: 50px -30px -20px -30px; + padding: 10px 20px; + background: #333; + color: white; + } + + div.sphinxsidebar h3, div.sphinxsidebar h4, div.sphinxsidebar p, + div.sphinxsidebar h3 a { + color: white; + } + + div.sphinxsidebar a { + color: #aaa; + } + + div.sphinxsidebar p.logo { + display: none; + } + + div.document { + width: 100%; + margin: 0; + } + + div.related { + display: block; + margin: 0; + padding: 10px 0 20px 0; + } + + div.related ul, + div.related ul li { + margin: 0; + padding: 0; + } + + div.footer { + display: none; + } + + div.bodywrapper { + margin: 0; + } + + div.body { + min-height: 0; + padding: 0; + } + + .rtd_doc_footer { + display: none; + } + + .document { + width: auto; + } + + .footer { + width: auto; + } + + .footer { + width: auto; + } + + .github { + display: none; + } +} + + /* scrollbars */ ::-webkit-scrollbar { @@ -420,3 +562,9 @@ a:hover tt { background-color: #ccc; -webkit-border-radius: 3px; } + +/* misc. */ + +.revsys-inline { + display: none!important; +} \ No newline at end of file From be23a5341b9a9c29bd18d93c999b4d1a431b01bc Mon Sep 17 00:00:00 2001 From: Dan Crosta Date: Fri, 30 Dec 2011 00:42:44 -0500 Subject: [PATCH 06/51] add by the community, for the community --- docs/intro/duction.rst | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/intro/duction.rst b/docs/intro/duction.rst index aa1cd77..0c3fe58 100644 --- a/docs/intro/duction.rst +++ b/docs/intro/duction.rst @@ -2,3 +2,29 @@ Introduction ============ Someone should write a general blurb introducing the Python language here + + +About the Hitchhiker's Guide +---------------------------- + +By the Community +~~~~~~~~~~~~~~~~ + +The Hitchhiker's Guide to Python is hosted in `Kenneth Reitz's GitHub +`_, but it is not by him. +Rather, it is a community-driven effort to document the best finds in +Python, tips and tricks from, help for choosing frameworks, libraries, and +licenses, and more. + +For the Community +~~~~~~~~~~~~~~~~~ + +All contributions to the Guide are welcome, from Pythonistas of all levels. +If you think there's a gap in what the Guide covers, fork the Guide on +GitHub and submit a pull request. Contributions are welcome from everyone, +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. From 149ad117d6807438f20a46696b070ac1b359852b Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 30 Dec 2011 00:53:41 -0500 Subject: [PATCH 07/51] BDFL and such --- docs/intro/duction.rst | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/docs/intro/duction.rst b/docs/intro/duction.rst index 0c3fe58..7ced04f 100644 --- a/docs/intro/duction.rst +++ b/docs/intro/duction.rst @@ -1,20 +1,26 @@ Introduction ============ -Someone should write a general blurb introducing the Python language here +Someone should write a general blurb introducing the Python language here. About the Hitchhiker's Guide ---------------------------- +Purpose +~~~~~~~ + +The Hitchhiker's Guide to Python exists to provide both novice and expert +Python developers a best-practice handbook to the installation, configuration, +and usage of Python on a daily basis. + + By the Community ~~~~~~~~~~~~~~~~ -The Hitchhiker's Guide to Python is hosted in `Kenneth Reitz's GitHub -`_, but it is not by him. -Rather, it is a community-driven effort to document the best finds in -Python, tips and tricks from, help for choosing frameworks, libraries, and -licenses, and more. +This guide is architected and maintained by `Kenneth Reitz +`_ in an open fashion. This is a +community-driven effort that serves one purpose: to serve the community. For the Community ~~~~~~~~~~~~~~~~~ @@ -28,3 +34,5 @@ appropriateness, completeness, or accuracy of a contribution. To get started working on The Hitchhiker's Guide, see the :doc:`/notes/contribute` page. + + From 1717f4d39bd4ebf0a78c181091e52b2f0fb204b6 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 30 Dec 2011 00:56:29 -0500 Subject: [PATCH 08/51] better intro/duction headings --- docs/intro/duction.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/intro/duction.rst b/docs/intro/duction.rst index 7ced04f..a6b9b1f 100644 --- a/docs/intro/duction.rst +++ b/docs/intro/duction.rst @@ -4,8 +4,8 @@ Introduction Someone should write a general blurb introducing the Python language here. -About the Hitchhiker's Guide ----------------------------- +About This Guide +---------------- Purpose ~~~~~~~ From d7f77e566151a16bdaa1ff52dfaa53c4630bf03c Mon Sep 17 00:00:00 2001 From: Dustin Rodrigues Date: Thu, 29 Dec 2011 22:00:05 -0800 Subject: [PATCH 09/51] fixed homebrew download url --- docs/starting/installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/starting/installation.rst b/docs/starting/installation.rst index 2fa0334..2bb06d9 100644 --- a/docs/starting/installation.rst +++ b/docs/starting/installation.rst @@ -15,7 +15,7 @@ package manager. Mxcl's `Homebrew `_ is the an To `install Homebrew `_, simply run: :: - $ ruby -e "$(curl -fsS http://gist.github.com/raw/323731/install_homebrew.rb)" + $ ruby -e "$(curl -fsS https://raw.github.com/gist/323731)" It's basic commands are **update**, **install**, and **remove**. From c9242633bf28904e69d3cf596b3c148621adda83 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 30 Dec 2011 01:02:55 -0500 Subject: [PATCH 10/51] todo --- TODO.rst | 14 +++----------- 1 file changed, 3 insertions(+), 11 deletions(-) diff --git a/TODO.rst b/TODO.rst index 61de3a5..af9093b 100644 --- a/TODO.rst +++ b/TODO.rst @@ -1,11 +1,3 @@ -* Build out TODO.rst -* Get some rhyme and reason into the project -* Setup basic skeleton - - installation - - codingstyle - - module distribution - - applications distribution - - virtualenv - - webdev - -.. todolist:: \ No newline at end of file +* Establish "use this" vs "alternatives are...." recommendations + +.. todolist:: \ No newline at end of file From 1fa10e6c76bdf1beedca9ec3a6c82ec2b45cf599 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 30 Dec 2011 01:06:00 -0500 Subject: [PATCH 11/51] todo headings --- docs/notes/contribute.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/notes/contribute.rst b/docs/notes/contribute.rst index 1848fbf..4ecb675 100644 --- a/docs/notes/contribute.rst +++ b/docs/notes/contribute.rst @@ -1,11 +1,15 @@ Contribute ----------- +~~~~~~~~~~ Python-guide is under active development, and contributors are welcome. If you have a feature request, suggestion, or bug report, please open a new issue on GitHub_. To submit patches, please send a pull request on GitHub_. Make sure you add yourself to AUTHORS_. + +Todo List +--------- + If you'd like to contribute, there's plenty to do. Here's a short todo_ list. .. include:: ../../TODO.rst From 3a65e06445ab95d02f4ad755fd060f4cc3e97b19 Mon Sep 17 00:00:00 2001 From: Matt Behrens Date: Thu, 29 Dec 2011 22:13:59 -0800 Subject: [PATCH 12/51] Simplify the linux install instructions and fix formatting --- docs/starting/installation.rst | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/starting/installation.rst b/docs/starting/installation.rst index 2fa0334..69b391c 100644 --- a/docs/starting/installation.rst +++ b/docs/starting/installation.rst @@ -128,15 +128,11 @@ Older versions of Python aren't available from the official repository. However, Installing setuptools and pip ----------------------------- -While Python has an extensive standard library, the set of packages available from the Internet is even more extensive. In order to install them easily, we'll install the ``setuptools`` package and ``pip`` installer:: - -.. XXX: sudo? +While Python has an extensive standard library, the set of packages available from the Internet is even more extensive. In order to install them easily, we'll install the ``distribute`` package and then ``pip``:: $ wget http://python-distribute.org/distribute_setup.py - $ python distribute_setup.py - $ wget https://raw.github.com/pypa/pip/master/contrib/get-pip.py - $ python get-pip.py - $ rm get-pip.py distribute_setup.py + $ sudo python distribute_setup.py + $ sudo easy_install pip Now, most Python packages can be installed using the ``pip`` command. For example, if we wanted to install Django:: From d5b074ef47dd2b7490e190b37f4411d5c7616149 Mon Sep 17 00:00:00 2001 From: Florent Delannoy Date: Fri, 30 Dec 2011 19:25:31 +1300 Subject: [PATCH 13/51] What's a hitchiker's guide without a "Don't panic!"? --- docs/index.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/index.rst b/docs/index.rst index f3b727a..fe5bde8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,6 +8,9 @@ The Hitchhikers Guide to Python! Welcome to The Hitchhiker's Guide to Python. +Don't panic! +============ + **This guide is currently under heavy development, and is mostly a skeleton at the moment.** If you'd like to help, `fork us on GitHub `_! This *opinionated* guide exists to provide both novice and expert Python developers a best-practice handbook to the installation, configuration, and usage of Python on a daily basis. From e03d247d2974464c161f64202181107a9d048eb8 Mon Sep 17 00:00:00 2001 From: George Gritsouk Date: Fri, 30 Dec 2011 02:08:13 -0500 Subject: [PATCH 14/51] Expanded the virtualenv section with an example workflow. --- docs/starting/dev-env.rst | 81 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) diff --git a/docs/starting/dev-env.rst b/docs/starting/dev-env.rst index b1f2498..c87a6d0 100644 --- a/docs/starting/dev-env.rst +++ b/docs/starting/dev-env.rst @@ -97,6 +97,87 @@ virtualenv 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 "Project X depends on version 1.x but, Project Y needs 4.x" dilemma and keeps your global site-packages directory clean and manageable. +`virtualenv `_ creates +a folder which contains all the necessary executables to contain the +packages that a Python project would need. An example workflow: + +Install virtualenv: + +:: + + $ pip install virtualenv + +or, depending on what's available: + +:: + + $ easy_install virtualenv + +Create a virtual environment for a project: + +:: + + $ cd my_project + $ virtualenv venv + +``virtualenv venv`` will create a folder in the currect directory +which will contain the Python executable files, and a copy of the ``pip`` +library which you can use to install other packages. The name of the +virtual environment (in this case, it was ``venv``) can be anything; +omitting the name will place the files in the current directory instead. + +In order the start using the virtual environment, run + +:: + + $ source venv/bin/activate + +or + +:: + + $ . venv/bin/activate + +The name of the current virtual environment will now appear on the left +of the prompt (e.g. ``(venv)Your-Computer:your_project UserName$``) to +let you know that it's active. From now on, any package that you install +using ``pip`` will be placed in the venv folder, isolated from the global +Python installation. + +To stop using an environment simply type ``deactivate``. To remove the +environment, just remove the directory it was installed into. (In this +case, it would be ``rm -rf venv``. + +Other Notes +~~~~~~~~~~~ + +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. + +In order to keep your environment consistent, it's a good idea to "freeze" +the current state of the environment packages. To do this, run + +:: + + pip freeze > requirements.txt + +This will create a ``requirements.txt`` file, which contains a simple +list of all the packages in the current environment, and their respective +versions. Later, when a different developer (or you, if you need to re- +create the environment) can install the same packages, with the same +versions by running + +:: + + pip install -r requirements.txt + +This can help ensure consistency across installations, across deployments, +and across developers. + +Lastly, remember to exclude the virtual environment folder from source +control by adding it to the ignore list. + virtualenvwrapper ----------------- From 00e76557b07bb80f6a8e4c0cfe7b1ed80d701a7f Mon Sep 17 00:00:00 2001 From: George Gritsouk Date: Fri, 30 Dec 2011 02:11:47 -0500 Subject: [PATCH 15/51] Fixed a missing bracket, added a small chunk to the example. --- docs/starting/dev-env.rst | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/starting/dev-env.rst b/docs/starting/dev-env.rst index c87a6d0..c3e3108 100644 --- a/docs/starting/dev-env.rst +++ b/docs/starting/dev-env.rst @@ -99,21 +99,21 @@ It solves the "Project X depends on version 1.x but, Project Y needs 4.x" dilemm `virtualenv `_ creates a folder which contains all the necessary executables to contain the -packages that a Python project would need. An example workflow: +packages that a Python project would need. An example workflow is given. -Install virtualenv: +Install virtualenv :: $ pip install virtualenv -or, depending on what's available: +or, depending on what's available :: $ easy_install virtualenv -Create a virtual environment for a project: +Create a virtual environment for a project :: @@ -142,11 +142,14 @@ The name of the current virtual environment will now appear on the left of the prompt (e.g. ``(venv)Your-Computer:your_project UserName$``) to let you know that it's active. From now on, any package that you install using ``pip`` will be placed in the venv folder, isolated from the global -Python installation. +Python installation. Install packages as usual. + +:: + $ pip install requests To stop using an environment simply type ``deactivate``. To remove the environment, just remove the directory it was installed into. (In this -case, it would be ``rm -rf venv``. +case, it would be ``rm -rf venv``). Other Notes ~~~~~~~~~~~ From 4043a5e18c1804b87ac681a59d313350853c6897 Mon Sep 17 00:00:00 2001 From: George Gritsouk Date: Fri, 30 Dec 2011 02:15:22 -0500 Subject: [PATCH 16/51] Added a missing space. --- docs/starting/dev-env.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/starting/dev-env.rst b/docs/starting/dev-env.rst index c3e3108..20a7904 100644 --- a/docs/starting/dev-env.rst +++ b/docs/starting/dev-env.rst @@ -145,6 +145,7 @@ using ``pip`` will be placed in the venv folder, isolated from the global Python installation. Install packages as usual. :: + $ pip install requests To stop using an environment simply type ``deactivate``. To remove the From 05f7ede1bdb2d24ef61afe4016c7b6a63d4afc07 Mon Sep 17 00:00:00 2001 From: Mike Thornton Date: Fri, 30 Dec 2011 01:20:28 -0600 Subject: [PATCH 17/51] Mostly added s, AUTHORS.rst, fixed some links, added some text editors --- AUTHORS.rst | 4 ++++ docs/intro/duction.rst | 3 +-- docs/intro/learning.rst | 8 ++------ docs/notes/contribute.rst | 3 ++- docs/notes/license.rst | 2 +- docs/scenarios/admin.rst | 12 +++++++++++- docs/scenarios/ci.rst | 15 ++++++++++----- docs/scenarios/cli.rst | 3 ++- docs/scenarios/db.rst | 4 ++++ docs/scenarios/gui.rst | 7 ++++--- docs/scenarios/speed.rst | 1 + docs/scenarios/web.rst | 6 ++++++ docs/shipping/freezing.rst | 3 +++ docs/shipping/packaging.rst | 6 +++++- docs/starting/dev-env.rst | 32 ++++++++++++++++++++++++++------ docs/writing/license.rst | 2 +- docs/writing/structure.rst | 1 + 17 files changed, 84 insertions(+), 28 deletions(-) create mode 100644 AUTHORS.rst diff --git a/AUTHORS.rst b/AUTHORS.rst new file mode 100644 index 0000000..6fef61c --- /dev/null +++ b/AUTHORS.rst @@ -0,0 +1,4 @@ +Authors +------- + +.. todo:: Add authors \ No newline at end of file diff --git a/docs/intro/duction.rst b/docs/intro/duction.rst index a6b9b1f..a96ca88 100644 --- a/docs/intro/duction.rst +++ b/docs/intro/duction.rst @@ -1,8 +1,7 @@ Introduction ============ -Someone should write a general blurb introducing the Python language here. - +.. todo:: write a general blurb introducing the Python language About This Guide ---------------- diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst index fadf351..01870fd 100644 --- a/docs/intro/learning.rst +++ b/docs/intro/learning.rst @@ -59,13 +59,9 @@ Advanced Pro Python ~~~~~~~~~~ -TODO: Write about this book - - `Pro Python `_ +.. todo:: Write about `Pro Python `_ Expert Python Programming ~~~~~~~~~~~~~~~~~~~~~~~~~ -TODO: Write about this book - - `Expert Python Programming `_ +.. todo:: Write about `Expert Python Programming `_ diff --git a/docs/notes/contribute.rst b/docs/notes/contribute.rst index 4ecb675..548c3a5 100644 --- a/docs/notes/contribute.rst +++ b/docs/notes/contribute.rst @@ -16,6 +16,7 @@ If you'd like to contribute, there's plenty to do. Here's a short todo_ list. .. _GitHub: http://github.com/kennethreitz/python-guide/ -.. _AUTHORS: http://github.com/kennethreitz/python-guide/blob/master/AUTHORS +.. _AUTHORS: http://github.com/kennethreitz/python-guide/blob/master/AUTHORS.rst .. _todo: https://github.com/kennethreitz/python-guide/blob/master/TODO.rst +.. include:: ../../AUTHORS.rst \ No newline at end of file diff --git a/docs/notes/license.rst b/docs/notes/license.rst index d03e7d1..d26b3c7 100644 --- a/docs/notes/license.rst +++ b/docs/notes/license.rst @@ -1,4 +1,4 @@ License ------- -TBD. \ No newline at end of file +.. todo:: Determine License \ No newline at end of file diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index f3a1492..1de9fa6 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -4,14 +4,24 @@ Systems Administration Fabric ------ +.. todo:: Write about Fabric Chef ---- +.. todo:: Write about Chef Puppet ------ +.. todo:: Write about Puppet Blueprint ---------- \ No newline at end of file +--------- + +.. todo:: Write about Blueprint + +Buildout +-------- + +.. todo:: Write about Buildout \ No newline at end of file diff --git a/docs/scenarios/ci.rst b/docs/scenarios/ci.rst index cd3d5dd..15166a2 100644 --- a/docs/scenarios/ci.rst +++ b/docs/scenarios/ci.rst @@ -5,23 +5,28 @@ Continuous Integration Why? ---- -Martin Fowler, who first wrote about Continuous Integration (short: CI) together with Kent Beck, describes the CI as follows: +Martin Fowler, who first wrote about `Continuous Integration `_ (short: CI) together with Kent Beck, describes the CI as follows: Continuous Integration is a software development practice where members of a team integrate their work frequently, usually each person integrates at least daily - leading to multiple integrations per day. Each integration is verified by an automated build (including test) to detect integration errors as quickly as possible. Many teams find that this approach leads to significantly reduced integration problems and allows a team to develop cohesive software more rapidly. This article is a quick overview of Continuous Integration summarizing the technique and its current usage. -Source: http://martinfowler.com/articles/continuousIntegration.html - Jenkins ------- -Jenkins CI (http://jenkins-ci.org) is an extensible continuous integration engine. Use it. +`Jenkins CI `_ is an extensible continuous integration engine. Use it. Buildbot -------- -Buildbot (http://buildbot.net/buildbot/docs/current) is a Python system to automate the compile/test cycle to validate code changes. +`Buildbot `_ is a Python system to automate the compile/test cycle to validate code changes. Mule? ----- + +.. todo:: Write about Mule + +Tox +--- + +.. todo:: Write about `Tox `_ diff --git a/docs/scenarios/cli.rst b/docs/scenarios/cli.rst index 216ad6b..cea7a3f 100644 --- a/docs/scenarios/cli.rst +++ b/docs/scenarios/cli.rst @@ -1,8 +1,9 @@ Command Line Applications ========================= - +.. todo:: Explain "Command Line Applications" Clint ----- +.. todo:: Write about Clint \ No newline at end of file diff --git a/docs/scenarios/db.rst b/docs/scenarios/db.rst index ad04d04..7b6ad95 100644 --- a/docs/scenarios/db.rst +++ b/docs/scenarios/db.rst @@ -22,3 +22,7 @@ database-agnostic code without SQL. pip install sqlalchemy +Django ORM +---------- + +.. todo:: Explain Django ORM \ No newline at end of file diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst index de4e47d..8572f7b 100644 --- a/docs/scenarios/gui.rst +++ b/docs/scenarios/gui.rst @@ -12,16 +12,17 @@ http://developer.qt.nokia.com/wiki/PySideDownloads/ PyQt ---- -*Note: If your software does not fully comply with the GPL you will need a commercial license!* +.. note:: If your software does not fully comply with the GPL you will need a commercial license! + http://www.riverbankcomputing.co.uk/software/pyqt/download Cocoa ::::: -*Note: The Cocoa framework is only available on Mac OSX. Don't pick this if you're writing a cross-platform application!* +.. note:: The Cocoa framework is only available on Mac OSX. Don't pick this if you're writing a cross-platform application! PyObjC ------ -*Note: Only available on Mac OSX. Don't pick this if you're writing a cross-platform application.* +.. note:: Only available on Mac OSX. Don't pick this if you're writing a cross-platform application. WXPython :::::::: diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst index 5a4bd13..81e695c 100644 --- a/docs/scenarios/speed.rst +++ b/docs/scenarios/speed.rst @@ -3,6 +3,7 @@ Speed CPython, the most commonly used implementation of Python, is slow for CPU bound tasks. `PyPy`_ is fast. +.. todo:: Fill in stub for Speed comparisons Context ::::::: diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst index 60a478d..8d0ebe5 100644 --- a/docs/scenarios/web.rst +++ b/docs/scenarios/web.rst @@ -74,10 +74,13 @@ already exist to suit your needs. Pyramid ------- +.. todo:: Explian Pyramid Servers ::::::: +.. todo:: Explain Apache deployment + Apache + mod_wsgi ----------------- @@ -107,6 +110,7 @@ setup for Nginx + gUnicorn can be found in the gUnicorn Mongrel2 + Brubeck ------------------ +.. todo:: Explain Mongrel2 + Brubeck Mongrel2 + wsgid ---------------- @@ -209,6 +213,8 @@ Gondor publishes guides to deploying `Django projects Shared Web Hosting ------------------ +.. todo:: Fill in "Shared Web Hosting" stub + WebFaction ~~~~~~~~~~~ diff --git a/docs/shipping/freezing.rst b/docs/shipping/freezing.rst index 1f9fd4a..b6803af 100644 --- a/docs/shipping/freezing.rst +++ b/docs/shipping/freezing.rst @@ -10,6 +10,9 @@ Many applications you use every day do this: - BitTorrent - + +.. todo:: Fill in "Freezing Your Code" stub + Windows ::::::: diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst index 40a0ac4..28762e1 100644 --- a/docs/shipping/packaging.rst +++ b/docs/shipping/packaging.rst @@ -3,6 +3,7 @@ Packaging Your Code Packaging your code is important. +.. todo:: Write introduction for "Packaging Your Code" For Python Developers ::::::::::::::::::::: @@ -14,7 +15,7 @@ If you're writing an open source Python module, `PyPI `_ Pip vs. easy_install -------------------- -Use pip. More details `here `_ +Use `pip `_. More details `here `_ Personal PyPI @@ -54,10 +55,13 @@ $ pip install http://127.0.0.1:9000/MyPackage.tar.gz Chishop +++++++ +`Chishop `_ is a simple PyPI server written in django which allows you to register/upload with distutils and install with easy_install/pip. For Linux Distributions :::::::::::::::::::::::: +.. todo:: Fill in "For Linux Distributions" packaging stub + Useful Tools ------------ diff --git a/docs/starting/dev-env.rst b/docs/starting/dev-env.rst index b1f2498..bdee749 100644 --- a/docs/starting/dev-env.rst +++ b/docs/starting/dev-env.rst @@ -54,6 +54,19 @@ the following lines into your vimrc:: .. todo:: add supertab notes +TextMate +-------- + +"`TextMate `_ brings Apple's approach to operating systems into the world of text editors. By bridging UNIX underpinnings and GUI, TextMate cherry-picks the best of both worlds to the benefit of expert 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 uses Python for its plugin API. + +`Sublime Text 2 `_ is currently in beta. IDEs :::: @@ -61,7 +74,7 @@ IDEs PyCharm / IntelliJ IDEA ----------------------- -PyCharm is developed by JetBrains, also known for IntelliJ IDEA. Both share the same code base and most of PyCharm's features can be brought to IntelliJ with the free `Python Plug-In `_.. +`PyCharm `_ is developed by JetBrains, also known for IntelliJ IDEA. Both share the same code base and most of PyCharm's features can be brought to IntelliJ with the free `Python Plug-In `_. Eclipse ------- @@ -82,8 +95,7 @@ Spyder Includes integration with `pyflakes `_, `pylint `_, and `rope `_. -Spyder is open-source (free), offers code completion, syntax highlighting, class and function browser, and object -inspection +Spyder is open-source (free), offers code completion, syntax highlighting, class and function browser, and object inspection. @@ -100,7 +112,7 @@ It solves the "Project X depends on version 1.x but, Project Y needs 4.x" dilemm virtualenvwrapper ----------------- -Virtualenvwrapper makes virtualenv a pleasure to use by wrapping the command line API with a nicer CLI. +`Virtualenvwrapper `_ makes virtualenv a pleasure to use by wrapping the command line API with a nicer CLI. :: @@ -121,9 +133,17 @@ Other Tools IPython ------- +`IPython `_ provides a rich toolkit to help you make the most out of using Python interactively. Its main components are: + +* Powerful Python shells (terminal- and Qt-based). +* A web-based notebook with the same core features but support for rich media, text, code, mathematical expressions and inline plots. +* Support for interactive data visualization and use of GUI toolkits. +* Flexible, embeddable interpreters to load into your own projects. +* Tools for high level and interactive parallel computing. + :: - $ pip install ipython + pip install ipython @@ -132,6 +152,6 @@ BPython :: - $ pip install bpython + pip install bpython diff --git a/docs/writing/license.rst b/docs/writing/license.rst index 6d91fea..739271d 100644 --- a/docs/writing/license.rst +++ b/docs/writing/license.rst @@ -4,7 +4,7 @@ Choosing a License Open source. - +.. todo:: Fill in License stub Non-Restrictive diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index 849bdea..b83f09a 100644 --- a/docs/writing/structure.rst +++ b/docs/writing/structure.rst @@ -3,6 +3,7 @@ Structuring Your Project Structuring your project properly is extremely important. +.. todo:: Fill in "Structuring Your Project" stub Structure is Key ---------------- From 15a098e6819c736215622a7c951bacfcf58763e2 Mon Sep 17 00:00:00 2001 From: Mike Thornton Date: Fri, 30 Dec 2011 01:28:01 -0600 Subject: [PATCH 18/51] Added authors from http://late.am/post/2011/12/29/hitchhikers-guide-to-python --- AUTHORS.rst | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/AUTHORS.rst b/AUTHORS.rst index 6fef61c..0b93bfe 100644 --- a/AUTHORS.rst +++ b/AUTHORS.rst @@ -1,4 +1,16 @@ Authors ------- -.. todo:: Add authors \ No newline at end of file +* `Kenneth Reitz `_ (follow on `Twitter `_ & `GitHub `_) +* `Aaron Weinberger `_ (follow on `GitHub `_) +* `Kamil Kisiel `_ (follow on `Twitter `_ & `GitHub `_) +* `Seyi Ogunyemi `_ (follow on `Twitter `_ & `GitHub `_) +* `Alex Gaynor `_ (follow on `Twitter `_ & `Github `_) +* `nstielau `_ (follow on `GitHub `_) +* `Adam Brenecki `_ (follow on `Twitter `_ & `GitHub `_) +* `Nanda Kishore `_ (follow on `GitHub `_) +* `Donald Stufft `_ (follow on `Twitter `_ and `GitHub `_) +* `Brent O'Connor `_ (follow on `Twitter `_ & `GitHub `_) +* `Dalton Barreto `_ (follow on `Twitter `_ & `GitHub `_) +* `Daniel Schauenberg `_ (follow on `Twitter `_ & `GitHub `_) +* `Mike Thornton `_ (follow on `GitHub `_) \ No newline at end of file From 8cac29364e227b43afc877bcd9dda813a8e450b5 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Fri, 30 Dec 2011 11:21:45 +0100 Subject: [PATCH 19/51] dev-env.rst: Remove duplicate link target for Pyflakes --- docs/starting/dev-env.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/starting/dev-env.rst b/docs/starting/dev-env.rst index b1f2498..062dd55 100644 --- a/docs/starting/dev-env.rst +++ b/docs/starting/dev-env.rst @@ -79,7 +79,7 @@ Spyder ------ `Spyder `_ an IDE specifically geared toward working with scientific python libraries (namely `Scipy `_). -Includes integration with `pyflakes `_, `pylint `_, +Includes integration with pyflakes_, `pylint `_, and `rope `_. Spyder is open-source (free), offers code completion, syntax highlighting, class and function browser, and object From 1db52a589146b1f9a62a65f5cad78b89caa7a621 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stephan=20H=C3=BCgel?= Date: Fri, 30 Dec 2011 15:18:40 +0000 Subject: [PATCH 20/51] Fixing typo in LaTeX source --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 93ebaec..ccc36c4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -182,7 +182,7 @@ htmlhelp_basename = 'pythonguidedoc' # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ - ('index', 'pythonguide.tex', u'Pythong Guide Documentation', + ('index', 'pythonguide.tex', u'Python Guide Documentation', u'Kenneth Reitz', 'manual'), ] From e7015577068c47078a98435c97e225e0e199ea57 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 30 Dec 2011 10:38:21 -0500 Subject: [PATCH 21/51] Update docs/index.rst --- docs/index.rst | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index fe5bde8..9afd305 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,10 +6,7 @@ The Hitchhikers Guide to Python! ================================ -Welcome to The Hitchhiker's Guide to Python. - -Don't panic! -============ +Welcome to The Hitchhiker's Guide to Python. **Don't Panic!** **This guide is currently under heavy development, and is mostly a skeleton at the moment.** If you'd like to help, `fork us on GitHub `_! From d05c08cb07980e75eae7790e1a3382d898b3d1ee Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 30 Dec 2011 10:45:48 -0500 Subject: [PATCH 22/51] Adding $ back in #46 --- docs/starting/dev-env.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/starting/dev-env.rst b/docs/starting/dev-env.rst index 905274f..6aac666 100644 --- a/docs/starting/dev-env.rst +++ b/docs/starting/dev-env.rst @@ -79,7 +79,7 @@ PyCharm / IntelliJ IDEA Eclipse ------- -The most popular Eclipse plugin for Python development is Aptana's +The most popular Eclipse plugin for Python development is Aptana's `PyDev `_. @@ -88,7 +88,7 @@ Komodo IDE `Komodo IDE `_ is developed by ActiveState and is a commerical IDE for Windows, Mac and Linux. -Spyder +Spyder ------ `Spyder `_ an IDE specifically geared toward working with scientific python libraries (namely `Scipy `_). @@ -176,7 +176,7 @@ the current state of the environment packages. To do this, run :: - pip freeze > requirements.txt + $ pip freeze > requirements.txt This will create a ``requirements.txt`` file, which contains a simple list of all the packages in the current environment, and their respective @@ -186,7 +186,7 @@ versions by running :: - pip install -r requirements.txt + $ pip install -r requirements.txt This can help ensure consistency across installations, across deployments, and across developers. @@ -201,14 +201,14 @@ virtualenvwrapper :: - pip install virtualenvwrapper + $ pip install virtualenvwrapper Put this into your `~/.bash_profile` (Linux/Mac) file: :: - export VIRTUALENVWRAPPER_VIRTUALENV_ARGS='--no-site-packages' + $ export VIRTUALENVWRAPPER_VIRTUALENV_ARGS='--no-site-packages' This will prevent your virtualenvs from relying on your (global) site packages directory, so that they are completely separate.. @@ -228,7 +228,7 @@ IPython :: - pip install ipython + $ pip install ipython @@ -237,6 +237,6 @@ BPython :: - pip install bpython + $ pip install bpython From 51c32b84ec5e08b1fd0ed8d1dd98f0a6c990b76d Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 30 Dec 2011 10:46:55 -0500 Subject: [PATCH 23/51] dev env cleanup --- docs/starting/dev-env.rst | 26 ++++---------------------- 1 file changed, 4 insertions(+), 22 deletions(-) diff --git a/docs/starting/dev-env.rst b/docs/starting/dev-env.rst index 6aac666..b957faa 100644 --- a/docs/starting/dev-env.rst +++ b/docs/starting/dev-env.rst @@ -113,21 +113,12 @@ It solves the "Project X depends on version 1.x but, Project Y needs 4.x" dilemm a folder which contains all the necessary executables to contain the packages that a Python project would need. An example workflow is given. -Install virtualenv - -:: +Install virtualenv:: $ pip install virtualenv -or, depending on what's available -:: - - $ easy_install virtualenv - -Create a virtual environment for a project - -:: +Create a virtual environment for a project:: $ cd my_project $ virtualenv venv @@ -138,25 +129,16 @@ library which you can use to install other packages. The name of the virtual environment (in this case, it was ``venv``) can be anything; omitting the name will place the files in the current directory instead. -In order the start using the virtual environment, run - -:: +In order the start using the virtual environment, run:: $ source venv/bin/activate -or - -:: - - $ . venv/bin/activate The name of the current virtual environment will now appear on the left of the prompt (e.g. ``(venv)Your-Computer:your_project UserName$``) to let you know that it's active. From now on, any package that you install using ``pip`` will be placed in the venv folder, isolated from the global -Python installation. Install packages as usual. - -:: +Python installation. Install packages as usual:: $ pip install requests From ed9691d6579ff170f7faa73c1f179c3064f5a86d Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 30 Dec 2011 10:48:49 -0500 Subject: [PATCH 24/51] no AUTHORS again --- AUTHORS.rst | 16 ---------------- docs/notes/contribute.rst | 7 ++++--- 2 files changed, 4 insertions(+), 19 deletions(-) delete mode 100644 AUTHORS.rst diff --git a/AUTHORS.rst b/AUTHORS.rst deleted file mode 100644 index 0b93bfe..0000000 --- a/AUTHORS.rst +++ /dev/null @@ -1,16 +0,0 @@ -Authors -------- - -* `Kenneth Reitz `_ (follow on `Twitter `_ & `GitHub `_) -* `Aaron Weinberger `_ (follow on `GitHub `_) -* `Kamil Kisiel `_ (follow on `Twitter `_ & `GitHub `_) -* `Seyi Ogunyemi `_ (follow on `Twitter `_ & `GitHub `_) -* `Alex Gaynor `_ (follow on `Twitter `_ & `Github `_) -* `nstielau `_ (follow on `GitHub `_) -* `Adam Brenecki `_ (follow on `Twitter `_ & `GitHub `_) -* `Nanda Kishore `_ (follow on `GitHub `_) -* `Donald Stufft `_ (follow on `Twitter `_ and `GitHub `_) -* `Brent O'Connor `_ (follow on `Twitter `_ & `GitHub `_) -* `Dalton Barreto `_ (follow on `Twitter `_ & `GitHub `_) -* `Daniel Schauenberg `_ (follow on `Twitter `_ & `GitHub `_) -* `Mike Thornton `_ (follow on `GitHub `_) \ No newline at end of file diff --git a/docs/notes/contribute.rst b/docs/notes/contribute.rst index 548c3a5..e5e66cc 100644 --- a/docs/notes/contribute.rst +++ b/docs/notes/contribute.rst @@ -3,8 +3,10 @@ Contribute Python-guide is under active development, and contributors are welcome. -If you have a feature request, suggestion, or bug report, please open a new issue on GitHub_. To submit patches, please send a pull request on GitHub_. Make sure you add yourself to AUTHORS_. - +If you have a feature request, suggestion, or bug report, please open a new +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 `_. Todo List @@ -16,7 +18,6 @@ If you'd like to contribute, there's plenty to do. Here's a short todo_ list. .. _GitHub: http://github.com/kennethreitz/python-guide/ -.. _AUTHORS: http://github.com/kennethreitz/python-guide/blob/master/AUTHORS.rst .. _todo: https://github.com/kennethreitz/python-guide/blob/master/TODO.rst .. include:: ../../AUTHORS.rst \ No newline at end of file From 19111aa51728fa0f03f9faace5856566418f0bd2 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 30 Dec 2011 10:49:17 -0500 Subject: [PATCH 25/51] todo: style guide --- TODO.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/TODO.rst b/TODO.rst index af9093b..af1790d 100644 --- a/TODO.rst +++ b/TODO.rst @@ -1,3 +1,4 @@ * Establish "use this" vs "alternatives are...." recommendations +* Style Guide (for Guide) .. todolist:: \ No newline at end of file From 32f664aa3dc9039dac78861e013f3c1403282a2d Mon Sep 17 00:00:00 2001 From: John Del Rosario Date: Sat, 31 Dec 2011 00:46:52 +0800 Subject: [PATCH 26/51] Add full Zen of Python in Code Style section. --- docs/writing/style.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/writing/style.rst b/docs/writing/style.rst index 216c780..803dca1 100644 --- a/docs/writing/style.rst +++ b/docs/writing/style.rst @@ -16,6 +16,27 @@ Also known as PEP 20, the guiding principles for Python's design. :: >>> import this + The Zen of Python, by Tim Peters + + Beautiful is better than ugly. + Explicit is better than implicit. + Simple is better than complex. + Complex is better than complicated. + Flat is better than nested. + Sparse is better than dense. + Readability counts. + Special cases aren't special enough to break the rules. + Although practicality beats purity. + Errors should never pass silently. + Unless explicitly silenced. + In the face of ambiguity, refuse the temptation to guess. + There should be one-- and preferably only one --obvious way to do it. + Although that way may not be obvious at first unless you're Dutch. + Now is better than never. + Although never is often better than *right* now. + If the implementation is hard to explain, it's a bad idea. + If the implementation is easy to explain, it may be a good idea. + Namespaces are one honking great idea -- let's do more of those! See ``_ for some examples. From 9871d401aa317b980e99f3f57062a9df104b0ce3 Mon Sep 17 00:00:00 2001 From: Tomas Thor Jonsson Date: Fri, 30 Dec 2011 18:34:16 +0100 Subject: [PATCH 27/51] typo fix in title --- docs/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 9afd305..fc9d450 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,8 +3,8 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -The Hitchhikers Guide to Python! -================================ +The Hitchhiker's Guide to Python! +================================= Welcome to The Hitchhiker's Guide to Python. **Don't Panic!** From dbb1ec6488afb2d4388fa055b5489c74877a8b40 Mon Sep 17 00:00:00 2001 From: Steve Pulec Date: Fri, 30 Dec 2011 13:28:48 -0500 Subject: [PATCH 28/51] Adding Fabric overview and example --- docs/scenarios/admin.rst | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index 1de9fa6..ed3c577 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -4,7 +4,41 @@ Systems Administration Fabric ------ -.. todo:: Write about Fabric +Fabric is a library for simplifying system administration tasks. While Chef +and Puppet tend to focus on managing servers and system libraries, +fabric is more focused on application level tasks such as deployment. + +Install Fabric: + +:: + + pip install fabric + +The following code will ssh into both of our servers, cd to our project +directory, activate the virtual environment, pull the newest codebase, +and restart the application server. + +:: + + from fabric.api import env, cd, run, prefix + + env.hosts = ['my_server1', 'my_server2'] + + def deploy(): + with cd('/var/www/project-env/project'): + with prefix('. ../bin/activate'): + run('git pull') + run('touch app.wsgi') + +With the previous code saved in a file named fabfile.py, we merely need to run +the following command to deploy our application to both of our servers. + +:: + + $ fab deploy + +Additional features include parallel execution, interaction with remote +programs, and host grouping. Chef ---- From 6664c2721b3356ebaa066ad587af8a9752418b5d Mon Sep 17 00:00:00 2001 From: mrshu Date: Fri, 30 Dec 2011 18:45:36 +0000 Subject: [PATCH 29/51] DON'T PANIC! shall be always uppercase. --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 9afd305..a0307c3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,7 +6,7 @@ The Hitchhikers Guide to Python! ================================ -Welcome to The Hitchhiker's Guide to Python. **Don't Panic!** +Welcome to The Hitchhiker's Guide to Python. **DON'T PANIC!** **This guide is currently under heavy development, and is mostly a skeleton at the moment.** If you'd like to help, `fork us on GitHub `_! From 9a92f89919aad0681ee307e9364944c140f0871e Mon Sep 17 00:00:00 2001 From: Steve Pulec Date: Fri, 30 Dec 2011 14:25:41 -0500 Subject: [PATCH 30/51] Add task decorator to fabric example --- docs/scenarios/admin.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index ed3c577..84a9189 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -20,10 +20,11 @@ and restart the application server. :: - from fabric.api import env, cd, run, prefix + from fabric.api import cd, env, prefix, run, task env.hosts = ['my_server1', 'my_server2'] + @task def deploy(): with cd('/var/www/project-env/project'): with prefix('. ../bin/activate'): From 69ef7c6ccbd08ead6a692c1354abcb34552b249c Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 30 Dec 2011 14:25:15 -0600 Subject: [PATCH 31/51] Note the speed difference. --- docs/starting/which-python.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/starting/which-python.rst b/docs/starting/which-python.rst index 9a22bc4..f5be900 100644 --- a/docs/starting/which-python.rst +++ b/docs/starting/which-python.rst @@ -66,7 +66,8 @@ PyPy aims for maximum compatibility with the reference CPython implementation while improving performance. If you are looking to squeeze more performance out of your Python code, it's -worth giving PyPy a try. +worth giving PyPy a try. On a suite of benchmarks, it's current `over 5 times +faster than CPython `_. Currently PyPy supports Python 2.7. From f6db35c9ec7d3211fa5c0bb3abc9cafeba4efbd3 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 30 Dec 2011 14:31:21 -0600 Subject: [PATCH 32/51] A bit more stuff on text editing. --- docs/starting/dev-env.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/starting/dev-env.rst b/docs/starting/dev-env.rst index b957faa..14904ba 100644 --- a/docs/starting/dev-env.rst +++ b/docs/starting/dev-env.rst @@ -5,6 +5,9 @@ Your Development Environment Text Editors :::::::::::: +Just about anything which can edit plain text will work for writing Python code, +however, using a more powerful editor may make your life a bit easier. + VIM --- @@ -62,9 +65,12 @@ TextMate 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, html and prose. You'll love the slick user interface and +extraordinary features." -Sublime Text uses Python for its plugin API. +Sublime Text has excellent support for editing Python code and uses Python for +its plugin API. `Sublime Text 2 `_ is currently in beta. From cd03e3a3a5dd6237105b54e6db07ee23f4db02f0 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 30 Dec 2011 14:37:24 -0600 Subject: [PATCH 33/51] notes on mod_python --- docs/scenarios/web.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst index 8d0ebe5..d6b0f89 100644 --- a/docs/scenarios/web.rst +++ b/docs/scenarios/web.rst @@ -87,6 +87,12 @@ Apache + mod_wsgi Apache + mod_python ------------------- +For a long period Apache with mod_python was one of the most reccomended +ways to deploy Python applications and thus you may see many tutorials +about it on the web or in books, however Apache no longer supports +mod_python and thus this deployment mechanism is strongly discouraged in +favor of WSGI based ones. + Nginx + gunicorn ---------------- From 909bd3963534325a45b35486e1f2873ccf856c0f Mon Sep 17 00:00:00 2001 From: Mike Thornton Date: Fri, 30 Dec 2011 16:36:19 -0600 Subject: [PATCH 34/51] First pass at styleguide --- TODO.rst | 1 - docs/contents.rst.inc | 2 +- docs/intro/duction.rst | 2 + docs/notes/contribute.rst | 6 ++ docs/notes/styleguide.rst | 132 +++++++++++++++++++++++++++++++++ docs/writing/documentation.rst | 13 +++- 6 files changed, 153 insertions(+), 3 deletions(-) create mode 100644 docs/notes/styleguide.rst diff --git a/TODO.rst b/TODO.rst index af1790d..af9093b 100644 --- a/TODO.rst +++ b/TODO.rst @@ -1,4 +1,3 @@ * Establish "use this" vs "alternatives are...." recommendations -* Style Guide (for Guide) .. todolist:: \ No newline at end of file diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc index 515c0a4..6355029 100644 --- a/docs/contents.rst.inc +++ b/docs/contents.rst.inc @@ -84,4 +84,4 @@ Contibution notes and legal information are here (for those interested). :maxdepth: 2 notes/contribute - notes/license + notes/license diff --git a/docs/intro/duction.rst b/docs/intro/duction.rst index a96ca88..0bd99e7 100644 --- a/docs/intro/duction.rst +++ b/docs/intro/duction.rst @@ -3,6 +3,8 @@ Introduction .. todo:: write a general blurb introducing the Python language +.. _about-ref: + About This Guide ---------------- diff --git a/docs/notes/contribute.rst b/docs/notes/contribute.rst index e5e66cc..3caf758 100644 --- a/docs/notes/contribute.rst +++ b/docs/notes/contribute.rst @@ -8,6 +8,12 @@ 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 `_. +Style Guide +----------- + +For all contributions, please follow the :ref:`guide-style-guide`. + +.. _todo-list-ref: Todo List --------- diff --git a/docs/notes/styleguide.rst b/docs/notes/styleguide.rst new file mode 100644 index 0000000..2bbc887 --- /dev/null +++ b/docs/notes/styleguide.rst @@ -0,0 +1,132 @@ +.. _guide-style-guide: + +===================== +The Guide Style Guide +===================== + +As with all documentation, having a consistent formating helps make the document more understandable. In order to make The Guide easier to digest, all contributions should fit within the rules of this style guide where approriate. + +The Guide is written as :ref:`restructuredtext-ref`. + +.. note:: Parts of The Guide may not yet match this style guide. Feel free to update those parts to by in sync with The Guide Style Guide + +.. note:: On any page of the rendered HTML you can click "Show Source" to see how authors have styled the page. + +Relevancy +--------- + +Stride to keep any contributions relevant to the :ref:`purpose of The Guide `. + +* Avoid including too much information on subjects that don't directly relate to Python development. +* Prefer to link to other sources if the information is already out there. Be sure to describe what and why you are linking. +* `Cite `_ references where needed. +* If a subject isn't directly relevant to Python, but useful in conjuction with Python (ex: Git, Github, Databases), reference by linking to useful resouces and describe why it's useful to Python. +* When in doubt, ask. + +Headings +-------- + +Use the following styles for headings. + +Chapter title:: + + ######### + Chapter 1 + ######### + +Page title:: + + =================== + Time is an Illusion + =================== + +Section headings:: + + Lunchtime Doubly So + ------------------- + +Sub section headings:: + + Very Deep + ~~~~~~~~~ + +Code Examples +------------- + +Wrap all code examples within 70 characters to avoid horizontal scrollbars. + +Command line examples:: + + .. code-block:: console + + $ run command --help + $ ls .. + +Be sure to include the ``$`` prefix before each line. + +Python interpreter examples:: + + Label the example:: + + >>> import this + +Python examples:: + + Descriptive title:: + + def get_answer(): + return 42 + +Externally Linking +------------------ + +* Prefer labels for well known subjects (ex: proper nouns) when linking:: + + Sphinx_ is used to document Python. + + .. _Sphinx: http://sphinx.pocoo.org + +* Prefer to use descriptive labels with inline links instead of leaving bare links:: + + Read the `Sphinx Tutorial `_ + +* Avoid using labels such as "click here", "this", etc. preferring decriptive labels (SEO worthy) instead. + +Linking to Sections in The Guide +-------------------------------- + +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:: + + .. _some-section-ref: + + Some Section + ------------ + +Notes and Warnings +------------------ + +Make use of the appropriate `admonitions directives `_ when making notes. + +Notes:: + + .. 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:: + + .. warning:: DON'T PANIC + +TODOs +----- + +Please mark any incomplete areas of The Guide with a `todo directive `_. To avoid cluttering the :ref:`todo-list-ref`, use a single ``todo`` for stub documents or large incomplete sections. + +:: + + .. todo:: + Learn the Ultimate Answer to the Ultimate Question + of Life, The Universe, and Everything \ No newline at end of file diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index 094a013..d1c4658 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -59,9 +59,20 @@ Multi-line docstrings: :: Sphinx ------ -Sphinx (http://sphinx.pocoo.org) is a tool which converts documentation in the reStructured text markup language into a range of output formats including HTML, LaTeX (for printable PDF versions), manual pages and plain text. +Sphinx_ is a tool which converts documentation in the :ref:`restructuredtext-ref` markup language into a range of output formats including HTML, LaTeX (for printable PDF versions), manual pages and plain text. +.. note:: This Guide is built with Sphinx_ +.. _Sphinx: http://sphinx.pocoo.org + +.. _restructuredtext-ref: + +reStructuredText +---------------- + +Most Python documentation is written with reStructuredText_. The `reStructuredText Primer `_ and the `reStructuredText Quick Reference `_ should help you familiarize yourself with its syntax. + +.. _reStructuredText: http://docutils.sourceforge.net/rst.html Other Tools ::::::::::: From 64b15c59bec363793530d40b382e7f03dcca4720 Mon Sep 17 00:00:00 2001 From: Steve Pulec Date: Fri, 30 Dec 2011 16:39:10 -0500 Subject: [PATCH 35/51] Add additional task to Fabric example --- docs/scenarios/admin.rst | 35 ++++++++++++++++++++++++++++++----- 1 file changed, 30 insertions(+), 5 deletions(-) diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index 84a9189..803db75 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -14,9 +14,11 @@ Install Fabric: pip install fabric -The following code will ssh into both of our servers, cd to our project -directory, activate the virtual environment, pull the newest codebase, -and restart the application server. +The following code will create two tasks that we can use: ``memory_usage`` and +``deploy``. The former will output the memory usage on each machine. The +latter will ssh into each server, cd to our project directory, activate the +virtual environment, pull the newest codebase, and restart the application +server. :: @@ -24,6 +26,10 @@ and restart the application server. env.hosts = ['my_server1', 'my_server2'] + @task + def memory_usage(): + run('free -m') + @task def deploy(): with cd('/var/www/project-env/project'): @@ -31,8 +37,27 @@ and restart the application server. run('git pull') run('touch app.wsgi') -With the previous code saved in a file named fabfile.py, we merely need to run -the following command to deploy our application to both of our servers. +With the previous code saved in a file named fabfile.py, we can check memory +usage with: + +:: + + $ fab memory_usage + [my_server1] Executing task 'memory' + [my_server1] run: free -m + [my_server1] out: total used free shared buffers cached + [my_server1] out: Mem: 6964 1897 5067 0 166 222 + [my_server1] out: -/+ buffers/cache: 1509 5455 + [my_server1] out: Swap: 0 0 0 + + [my_server2] Executing task 'memory' + [my_server2] run: free -m + [my_server2] out: total used free shared buffers cached + [my_server2] out: Mem: 1666 902 764 0 180 572 + [my_server2] out: -/+ buffers/cache: 148 1517 + [my_server2] out: Swap: 895 1 894 + +and we can deploy with: :: From d9439d5a9282003e546223370f69144448f56528 Mon Sep 17 00:00:00 2001 From: Steve Pulec Date: Fri, 30 Dec 2011 18:05:43 -0500 Subject: [PATCH 36/51] Clean up Fabric example to not have horizontal scroll --- docs/scenarios/admin.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index 803db75..512223e 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -45,17 +45,17 @@ usage with: $ fab memory_usage [my_server1] Executing task 'memory' [my_server1] run: free -m - [my_server1] out: total used free shared buffers cached - [my_server1] out: Mem: 6964 1897 5067 0 166 222 - [my_server1] out: -/+ buffers/cache: 1509 5455 - [my_server1] out: Swap: 0 0 0 + [my_server1] out: total used free shared buffers cached + [my_server1] out: Mem: 6964 1897 5067 0 166 222 + [my_server1] out: -/+ buffers/cache: 1509 5455 + [my_server1] out: Swap: 0 0 0 [my_server2] Executing task 'memory' [my_server2] run: free -m - [my_server2] out: total used free shared buffers cached - [my_server2] out: Mem: 1666 902 764 0 180 572 - [my_server2] out: -/+ buffers/cache: 148 1517 - [my_server2] out: Swap: 895 1 894 + [my_server2] out: total used free shared buffers cached + [my_server2] out: Mem: 1666 902 764 0 180 572 + [my_server2] out: -/+ buffers/cache: 148 1517 + [my_server2] out: Swap: 895 1 894 and we can deploy with: From a150dbe8791f9400b1b2c00fcb9a3ffb911d6781 Mon Sep 17 00:00:00 2001 From: Mike Thornton Date: Fri, 30 Dec 2011 17:41:19 -0600 Subject: [PATCH 37/51] Updated notes on Apache and added web server best practices --- docs/scenarios/web.rst | 119 +++++++++++++++++++++++++++++++---------- 1 file changed, 91 insertions(+), 28 deletions(-) diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst index d6b0f89..8c41c84 100644 --- a/docs/scenarios/web.rst +++ b/docs/scenarios/web.rst @@ -1,3 +1,4 @@ +================ Web Applications ================ @@ -13,7 +14,7 @@ The Web Server Gateway Interface (or "WSGI" for short) is a standard 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 `WSGI-compliant web server <#servers>`_. WSGI is +can be deployed in any :ref:`WSGI-compliant web server `. WSGI is documented in `PEP-3333 `_. @@ -76,26 +77,33 @@ Pyramid .. todo:: Explian Pyramid -Servers -::::::: +Web Servers +::::::::::: -.. todo:: Explain Apache deployment +Apache +------ -Apache + mod_wsgi ------------------ - -Apache + mod_python -------------------- +mod_python +~~~~~~~~~~ For a long period Apache with mod_python was one of the most reccomended ways to deploy Python applications and thus you may see many tutorials about it on the web or in books, however Apache no longer supports -mod_python and thus this deployment mechanism is strongly discouraged in +mod_python [1]_ and thus this deployment mechanism is strongly discouraged in favor of WSGI based ones. +mod_wsgi +~~~~~~~~ -Nginx + gunicorn ----------------- +Many improvements have been made with mod_wsgi over mod_python for serving +Python with Apache [2]_. If you must run the Apache web server, mod_wsgi is +your best option for running Python, other than proxying to a dedicated WSGI +server. + +.. _nginx-ref: + +Nginx +----- `Nginx `_ (pronounced "engine-x") is a web server and reverse-proxy for HTTP, SMTP and other protocols. It is known for its @@ -104,34 +112,83 @@ application servers (like WSGI servers). It also includes handy features like load-balancing, basic authentication, streaming, and others. Designed to serve high-load websites, Nginx is gradually becoming quite popular. +Mongrel2 +-------- + +`Mongrel2 `_ is an application, language, and network +architecture agnostic web server. It uses a high performance queue (zeromq) to +communicate with your applications, all asynchronously. There is a well defined +protocol to be used between mongrel2 and a backend handler (your app). + +Brubeck +~~~~~~~ + +.. todo:: Explain Mongrel2 + Brubeck + +wsgid +~~~~~ + +`Wsgid `_ is a generic mongrel2 handler that speaks both +mongrel2 protocol and WSGI. This makes it possible to run your python webapp +written with any WSGI compliant framework. Wsgid has built-in Django support but +has also a generic way to load your WSGI application object directly. It's +possible to add support for other frameworks through wsgid's pluggable +Apploading interface. + +.. rubric:: Resources + +* `Deploying your django application with mongrel2 and wsgid `_ + +.. _wsgi-servers-ref: + +WSGI Servers +:::::::::::: + +Stand-alone WSGI servers typically use less resources than traditional web +servers and provide top performance [3]_. + +.. _gunicorn-ref: + +gUnicorn +-------- + `gUnicorn `_ (Green Unicorn) is a WSGI server used to serve Python applications. It is a Python fork of the Ruby `Unicorn `_ server. gUnicorn is designed to be lightweight, easy to use, and uses many UNIX idioms. gUnicorn is not designed to face the internet, in fact it was designed to run behind Nginx which buffers slow requests, and takes care of other important considerations. A sample -setup for Nginx + gUnicorn can be found in the gUnicorn -`help `_. +setup for Nginx + gUnicorn can be found in the +`gUnicorn help `_. -Mongrel2 + Brubeck ------------------- +.. _uwsgi-ref: -.. todo:: Explain Mongrel2 + Brubeck +uwsgi +----- -Mongrel2 + wsgid ----------------- +`uWSGI `_ is a fast, self-healing and +developer/sysadmin-friendly application container server coded in pure C. -Mongrel2 is an application, language, and network architecture agnostic web server. It uses a high performance queue (zeromq) to communicate -with your applications, all asynchronously. There is a well defined protocol to be used between mongrel2 and a backend handler (your app). +Born as a WSGI-only server, over time it has evolved in a complete stack for +networked/clustered web applications, implementing message/object passing, +caching, RPC and process management. -Wsgid is a generic mongrel2 handler that speaks both mongrel2 protocol and WSGI. This makes it possible to run your python webapp written with any -WSGI compliant framework. Wsgid has built-in Django support but has also a generic way to load your WSGI application object directly. It's possible -to add support for other frameworks through wsgid's pluggable Apploading interface. +Server Best Practices +::::::::::::::::::::: -To know more about mongrel2 and wsgid go to: http://mongrel2.org and http://wsgid.com +While Apache will serve your Python application, and many references suggest it, +modern best practices suggest against it. With the improvements in mod_wsgi over +mod_python, Apache can handle many more requests than before. However, mod_wsgi +tends to use more memory than other WSGI solutions [3]_. -There is also a tutorial about deploying Django using this stack: http://daltonmatos.wordpress.com/2011/11/06/deploying-your-django-application-with-mongrel2-and-wsgid/ +The majority of self hosted Python applications today are hosted with a WSGI +server such as :ref:`uWSGI ` or :ref:`gUnicorn ` behind a +lightweight web server such as :ref:`nginx ` or +`lighttpd `_. +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 ::::::: @@ -177,8 +234,8 @@ DotCloud `DotCloud `_ supports WSGI applications and background/worker tasks natively on their platform. Web applications running -Python version 2.6, and uses `nginx `_ and `uWSGI -`_, and allows custom configuration of both +Python version 2.6, and uses :ref:`nginx ` and :ref:`uWSGI +`, and allows custom configuration of both for advanced users. DotCloud uses a custom command-line API client which can work with @@ -230,3 +287,9 @@ Twisted Node.js. + +.. rubric:: References + +.. [1] `The mod_python project is now officially dead `_ +.. [2] `mod_wsgi vs mod_python `_ +.. [3] `Benchmark of Python WSGI Servers `_ \ No newline at end of file From 4c68f91c8af679a1c6d86035906c5bad41e878c9 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Fri, 30 Dec 2011 19:14:25 -0500 Subject: [PATCH 38/51] $$$$$$$$$$$$$$$$$$$$$$ --- docs/scenarios/admin.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index 84a9189..f790a04 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -12,7 +12,7 @@ Install Fabric: :: - pip install fabric + $ pip install fabric The following code will ssh into both of our servers, cd to our project directory, activate the virtual environment, pull the newest codebase, From 73432c73681dc663946db0b3776c55ebe8656aee Mon Sep 17 00:00:00 2001 From: Steve Pulec Date: Fri, 30 Dec 2011 19:18:58 -0500 Subject: [PATCH 39/51] Fix missing dollar sign in fabric install --- docs/scenarios/admin.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index 512223e..b570d2b 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -12,7 +12,7 @@ Install Fabric: :: - pip install fabric + $ pip install fabric The following code will create two tasks that we can use: ``memory_usage`` and ``deploy``. The former will output the memory usage on each machine. The From 0b5a0efd92211ef29a189c489fe2c6d85931f132 Mon Sep 17 00:00:00 2001 From: Steve Pulec Date: Fri, 30 Dec 2011 19:24:28 -0500 Subject: [PATCH 40/51] Switch examples to code-block style --- docs/scenarios/admin.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index b570d2b..6271511 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -10,7 +10,7 @@ fabric is more focused on application level tasks such as deployment. Install Fabric: -:: +.. code-block:: bash $ pip install fabric @@ -20,7 +20,7 @@ latter will ssh into each server, cd to our project directory, activate the virtual environment, pull the newest codebase, and restart the application server. -:: +.. code-block:: python from fabric.api import cd, env, prefix, run, task @@ -40,7 +40,7 @@ server. With the previous code saved in a file named fabfile.py, we can check memory usage with: -:: +.. code-block:: bash $ fab memory_usage [my_server1] Executing task 'memory' @@ -59,7 +59,7 @@ usage with: and we can deploy with: -:: +.. code-block:: bash $ fab deploy From da8e3e89e2871ac8146f91e493890b56d9c0938c Mon Sep 17 00:00:00 2001 From: Steve Pulec Date: Fri, 30 Dec 2011 19:42:55 -0500 Subject: [PATCH 41/51] Remove unnecessary python code-block --- docs/scenarios/admin.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index 6271511..991cab2 100644 --- a/docs/scenarios/admin.rst +++ b/docs/scenarios/admin.rst @@ -20,7 +20,7 @@ latter will ssh into each server, cd to our project directory, activate the virtual environment, pull the newest codebase, and restart the application server. -.. code-block:: python +:: from fabric.api import cd, env, prefix, run, task From b9d9a1a22a83839c53910b6b46fc608584cf5629 Mon Sep 17 00:00:00 2001 From: Dan Crosta Date: Fri, 30 Dec 2011 19:47:18 -0500 Subject: [PATCH 42/51] wrap to 78chars, cleanup some trailing whitespace --- docs/notes/styleguide.rst | 68 +++++++++++++++++++++++++-------------- 1 file changed, 44 insertions(+), 24 deletions(-) diff --git a/docs/notes/styleguide.rst b/docs/notes/styleguide.rst index 2bbc887..33c804c 100644 --- a/docs/notes/styleguide.rst +++ b/docs/notes/styleguide.rst @@ -4,23 +4,34 @@ The Guide Style Guide ===================== -As with all documentation, having a consistent formating helps make the document more understandable. In order to make The Guide easier to digest, all contributions should fit within the rules of this style guide where approriate. +As with all documentation, having a consistent formating helps make the +document more understandable. In order to make The Guide easier to digest, +all contributions should fit within the rules of this style guide where +approriate. -The Guide is written as :ref:`restructuredtext-ref`. +The Guide is written as :ref:`restructuredtext-ref`. -.. note:: Parts of The Guide may not yet match this style guide. Feel free to update those parts to by in sync with The Guide Style Guide +.. note:: Parts of The Guide may not yet match this style guide. Feel free + to update those parts to by in sync with The Guide Style Guide -.. note:: On any page of the rendered HTML you can click "Show Source" to see how authors have styled the page. +.. note:: On any page of the rendered HTML you can click "Show Source" to + see how authors have styled the page. Relevancy --------- -Stride to keep any contributions relevant to the :ref:`purpose of The Guide `. +Stride to keep any contributions relevant to the :ref:`purpose of The Guide +`. -* Avoid including too much information on subjects that don't directly relate to Python development. -* Prefer to link to other sources if the information is already out there. Be sure to describe what and why you are linking. -* `Cite `_ references where needed. -* If a subject isn't directly relevant to Python, but useful in conjuction with Python (ex: Git, Github, Databases), reference by linking to useful resouces and describe why it's useful to Python. +* Avoid including too much information on subjects that don't directly + relate to Python development. +* Prefer to link to other sources if the information is already out there. + Be sure to describe what and why you are linking. +* `Cite `_ + references where needed. +* If a subject isn't directly relevant to Python, but useful in conjuction + with Python (ex: Git, Github, Databases), reference by linking to useful + resouces and describe why it's useful to Python. * When in doubt, ask. Headings @@ -49,7 +60,7 @@ Sub section headings:: Very Deep ~~~~~~~~~ - + Code Examples ------------- @@ -65,9 +76,9 @@ Command line examples:: Be sure to include the ``$`` prefix before each line. Python interpreter examples:: - + Label the example:: - + >>> import this Python examples:: @@ -75,7 +86,7 @@ Python examples:: Descriptive title:: def get_answer(): - return 42 + return 42 Externally Linking ------------------ @@ -86,16 +97,20 @@ Externally Linking .. _Sphinx: http://sphinx.pocoo.org -* Prefer to use descriptive labels with inline links instead of leaving bare links:: +* Prefer to use descriptive labels with inline links instead of leaving bare + links:: Read the `Sphinx Tutorial `_ -* Avoid using labels such as "click here", "this", etc. preferring decriptive labels (SEO worthy) instead. +* Avoid using labels such as "click here", "this", etc. preferring + decriptive labels (SEO worthy) instead. Linking to Sections in The Guide -------------------------------- -To cross-reference other parts of this documentation, use the `:ref: `_ keyword and labels. +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:: @@ -107,26 +122,31 @@ To make reference labels more clear and unique, always add a ``-ref`` suffix:: Notes and Warnings ------------------ -Make use of the appropriate `admonitions directives `_ when making notes. +Make use of the appropriate `admonitions directives +`_ when making notes. Notes:: - - .. note:: + + .. 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:: - + .. warning:: DON'T PANIC TODOs ----- -Please mark any incomplete areas of The Guide with a `todo directive `_. To avoid cluttering the :ref:`todo-list-ref`, use a single ``todo`` for stub documents or large incomplete sections. +Please mark any incomplete areas of The Guide with a `todo directive +`_. To +avoid cluttering the :ref:`todo-list-ref`, use a single ``todo`` for stub +documents or large incomplete sections. :: - .. todo:: - Learn the Ultimate Answer to the Ultimate Question - of Life, The Universe, and Everything \ No newline at end of file + .. todo:: + Learn the Ultimate Answer to the Ultimate Question + of Life, The Universe, and Everything + From f48d84826cb18daa588c53f598971549ab4e9ea1 Mon Sep 17 00:00:00 2001 From: Dan Crosta Date: Fri, 30 Dec 2011 19:53:47 -0500 Subject: [PATCH 43/51] text-wrapping; source code highlighting --- docs/notes/styleguide.rst | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/notes/styleguide.rst b/docs/notes/styleguide.rst index 33c804c..626d4a8 100644 --- a/docs/notes/styleguide.rst +++ b/docs/notes/styleguide.rst @@ -61,10 +61,18 @@ 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 +to read. + + Code Examples ------------- -Wrap all code examples within 70 characters to avoid horizontal scrollbars. +Wrap all code examples at 70 characters to avoid horizontal scrollbars. Command line examples:: @@ -79,12 +87,16 @@ Python interpreter examples:: Label the example:: + .. code-block:: python + >>> import this Python examples:: Descriptive title:: + .. code-block:: python + def get_answer(): return 42 From ab6fc7ced2b490197fe27357b427a2b9865fdb0d Mon Sep 17 00:00:00 2001 From: John Del Rosario Date: Sat, 31 Dec 2011 22:21:57 +0800 Subject: [PATCH 44/51] Add skeleton for 'Virtual Environments' Scenario page. --- docs/contents.rst.inc | 1 + docs/scenarios/virtualenvs.rst | 15 +++++++++++++++ 2 files changed, 16 insertions(+) create mode 100644 docs/scenarios/virtualenvs.rst diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc index 6355029..1effe99 100644 --- a/docs/contents.rst.inc +++ b/docs/contents.rst.inc @@ -72,6 +72,7 @@ different scenarios. scenarios/admin scenarios/ci scenarios/speed + scenarios/virtualenvs diff --git a/docs/scenarios/virtualenvs.rst b/docs/scenarios/virtualenvs.rst new file mode 100644 index 0000000..385fe94 --- /dev/null +++ b/docs/scenarios/virtualenvs.rst @@ -0,0 +1,15 @@ +Virtual Environments +==================== + +.. todo:: Explain "Virtual Environments" + +virtualenv +---------- + +.. todo:: Write about virtualenv + +virtualenvwrapper +----------------- + +.. todo:: Write about virtualenvwrapper + From 7a5b59f18504d0a6a55263d1e0ed1ce6c622e76f Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Sat, 31 Dec 2011 10:35:52 -0500 Subject: [PATCH 45/51] refactor of dev env sections #65 --- docs/contents.rst.inc | 14 ++++++++++---- docs/{starting/dev-env.rst => dev/env.rst} | 0 docs/{scenarios => dev}/virtualenvs.rst | 0 3 files changed, 10 insertions(+), 4 deletions(-) rename docs/{starting/dev-env.rst => dev/env.rst} (100%) rename docs/{scenarios => dev}/virtualenvs.rst (100%) diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc index 1effe99..de51208 100644 --- a/docs/contents.rst.inc +++ b/docs/contents.rst.inc @@ -24,10 +24,18 @@ This part of the guide focuses on setting up your Python environment. starting/which-python starting/installation - starting/dev-env starting/next +Development Environment +----------------------- + +.. toctree:: + :maxdepth: 2 + + dev/env + dev/virtualenvs + Writing Great Code ------------------ @@ -72,8 +80,6 @@ different scenarios. scenarios/admin scenarios/ci scenarios/speed - scenarios/virtualenvs - Additional Notes @@ -85,4 +91,4 @@ Contibution notes and legal information are here (for those interested). :maxdepth: 2 notes/contribute - notes/license + notes/license diff --git a/docs/starting/dev-env.rst b/docs/dev/env.rst similarity index 100% rename from docs/starting/dev-env.rst rename to docs/dev/env.rst diff --git a/docs/scenarios/virtualenvs.rst b/docs/dev/virtualenvs.rst similarity index 100% rename from docs/scenarios/virtualenvs.rst rename to docs/dev/virtualenvs.rst From 858aff1a7c47c0eab1789140b3d6f3c6da85c7ad Mon Sep 17 00:00:00 2001 From: Chewxy Date: Sun, 1 Jan 2012 06:44:47 +1100 Subject: [PATCH 46/51] Added Web.py in web.rst Added links to support in web.rst Added a chapter for Scientific/HighPerformance Python Signed-off-by: Chewxy --- docs/scenarios/scientific.rst | 50 +++++++++++++++++++++++++++++++++++ docs/scenarios/web.rst | 20 ++++++++++++++ 2 files changed, 70 insertions(+) create mode 100644 docs/scenarios/scientific.rst diff --git a/docs/scenarios/scientific.rst b/docs/scenarios/scientific.rst new file mode 100644 index 0000000..52a1efe --- /dev/null +++ b/docs/scenarios/scientific.rst @@ -0,0 +1,50 @@ +======================= +Scientific Applications +======================= + +Context +::::::: + +Python is frequently used for high-performance scientific applications. Python is widely used in academia +and scientific projects because it is easy to write, and it performs really well. + +Due to its high performance nature, scientific computing in python often refers to external libraries, typically +written in faster languages (like C, or FORTRAN for matrix operations). The main libraries used are NumPy and SciPy + +Libraries +::::::::: + +Numpy +----- +`NumPy `_ is a low level library written in C (and FORTRAN) for high level mathematical functions. +NumPy cleverly overcomes the problem of running slower algorithms on Python by using multidimensional arrays and functions that operate on arrays. +Any algorithm can then be expressed as a function on arrays, allowing the algorithms to be run quickly. + + +NumPy is part of the SciPy project, and is released as a separate library so people who only need the basic requirements can just use NumPy. + +NumPy is compatible with Python versions 2.4 through to 2.7.2 and 3.1+. + +SciPy +----- +`SciPy `_ is a library that uses Numpy for more mathematical function. SciPy uses NumPy arrays as its basic data structure. +SciPy comes with modules for various commonly used tasks in scientific programing like linear algebra, integration (calculus), +ordinary differential equation solvers and signal processing. + +Enthought +--------- + +Installing NumPy and SciPy can be a daunting task. Which is why the `Enthought Python distribution `_ was created. With Enthought, +scientific python has never been easier (one click to install about 100 scientific python packages). User beware: Enthought is not free. + +Matplotlib +---------- + +.. todo:: write about matplotlib. + +Resources +::::::::: + +Many people who do scientific computing are on Windows. And yet many of the scientific computing packages are notoriously difficult to build and install. +`Christoph Gohlke `_ however, has compiled a list of Windows binaries for many useful Python packages. +The list of packages has grown from a mainly scientific python resource to a more general list. It might be a good idea to check it out if you're on Windows. \ No newline at end of file diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst index 8c41c84..67f240f 100644 --- a/docs/scenarios/web.rst +++ b/docs/scenarios/web.rst @@ -71,12 +71,23 @@ you may need, such as database access or form generation and validation. For many popular modules, `Extensions `_ may already exist to suit your needs. +**Support** for flask can best be found in its mailing list. Just shoot an email to +flask@librelist.com and reply to the confirmation email. + Pyramid ------- .. todo:: Explian Pyramid +Web.py +------ + +`web.py `_ is a minimalist web framework that is somewhere between Django and Flask. +The premise of web.py is that it is flexible - code your webapp any way you want it, in just python and python alone. +web.py comes with some nifty tools built in, like database connection tools and a mini http server. + +**Support** for web.py is quite sparse, but you can look for support in the `mailing list `_ . Web Servers ::::::::::: @@ -281,6 +292,15 @@ Shared Web Hosting WebFaction ~~~~~~~~~~~ +`Webfaction `_ started off as a dedicated python hosting company. +In fact it used to be called python-hosting.com. Webfaction supports Python versions 2.4 through to 2.7.2 +as well as Python 3 versions. + +Webfaction has a very extensive `user guide `_ +and specific stack (`Django `_, `Pylons `_, +`Pyramid `_, `TurboGears `_ +and `vanilla python `_) guides. +It also has a stack-overflow style `community `_ that is quite useful. Twisted ::::::: From 06c6063e59665e0a80aea0e2dbd9a58fd2287ede Mon Sep 17 00:00:00 2001 From: mrshu Date: Sat, 31 Dec 2011 20:41:34 +0000 Subject: [PATCH 47/51] Removed unnecessary part of CI definition. --- docs/scenarios/ci.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/scenarios/ci.rst b/docs/scenarios/ci.rst index 15166a2..285e522 100644 --- a/docs/scenarios/ci.rst +++ b/docs/scenarios/ci.rst @@ -7,7 +7,7 @@ Why? Martin Fowler, who first wrote about `Continuous Integration `_ (short: CI) together with Kent Beck, describes the CI as follows: - Continuous Integration is a software development practice where members of a team integrate their work frequently, usually each person integrates at least daily - leading to multiple integrations per day. Each integration is verified by an automated build (including test) to detect integration errors as quickly as possible. Many teams find that this approach leads to significantly reduced integration problems and allows a team to develop cohesive software more rapidly. This article is a quick overview of Continuous Integration summarizing the technique and its current usage. + Continuous Integration is a software development practice where members of a team integrate their work frequently, usually each person integrates at least daily - leading to multiple integrations per day. Each integration is verified by an automated build (including test) to detect integration errors as quickly as possible. Many teams find that this approach leads to significantly reduced integration problems and allows a team to develop cohesive software more rapidly. Jenkins ------- From 0c9c889022bd4559e702ee73d2bf53d28ae983ea Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Sun, 1 Jan 2012 01:49:50 -0500 Subject: [PATCH 48/51] :sparkles: 2012 :sparkles: --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index ccc36c4..8e375c6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -41,7 +41,7 @@ master_doc = 'index' # General information about the project. project = u'pythonguide' -copyright = u'2011. A Kenneth Reitz Project' +copyright = u'2012. A Kenneth Reitz Project' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the From f4918a569cfef0fcf1adedd446762a4f7c4e3cf2 Mon Sep 17 00:00:00 2001 From: Kamil Kisiel Date: Mon, 2 Jan 2012 06:10:17 -0800 Subject: [PATCH 49/51] Fixed "web servers" heading --- docs/scenarios/web.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst index 67f240f..294c205 100644 --- a/docs/scenarios/web.rst +++ b/docs/scenarios/web.rst @@ -88,6 +88,8 @@ The premise of web.py is that it is flexible - code your webapp any way you want web.py comes with some nifty tools built in, like database connection tools and a mini http server. **Support** for web.py is quite sparse, but you can look for support in the `mailing list `_ . + + Web Servers ::::::::::: @@ -312,4 +314,4 @@ Node.js. .. [1] `The mod_python project is now officially dead `_ .. [2] `mod_wsgi vs mod_python `_ -.. [3] `Benchmark of Python WSGI Servers `_ \ No newline at end of file +.. [3] `Benchmark of Python WSGI Servers `_ From 8a8a6c794fe33cd262a13d7b4fb5e6d67fc35323 Mon Sep 17 00:00:00 2001 From: Kamil Kisiel Date: Mon, 2 Jan 2012 06:26:12 -0800 Subject: [PATCH 50/51] A variety of build error fixes --- docs/contents.rst.inc | 3 ++- docs/notes/contribute.rst | 2 -- docs/scenarios/gui.rst | 6 ++++-- docs/starting/installation.rst | 4 ---- docs/starting/next.rst | 0 docs/writing/documentation.rst | 11 ++++++++--- 6 files changed, 14 insertions(+), 12 deletions(-) delete mode 100644 docs/starting/next.rst diff --git a/docs/contents.rst.inc b/docs/contents.rst.inc index de51208..3f6f60a 100644 --- a/docs/contents.rst.inc +++ b/docs/contents.rst.inc @@ -24,7 +24,6 @@ This part of the guide focuses on setting up your Python environment. starting/which-python starting/installation - starting/next Development Environment @@ -80,6 +79,7 @@ different scenarios. scenarios/admin scenarios/ci scenarios/speed + scenarios/scientific Additional Notes @@ -92,3 +92,4 @@ Contibution notes and legal information are here (for those interested). notes/contribute notes/license + notes/styleguide diff --git a/docs/notes/contribute.rst b/docs/notes/contribute.rst index 3caf758..0d709f2 100644 --- a/docs/notes/contribute.rst +++ b/docs/notes/contribute.rst @@ -25,5 +25,3 @@ If you'd like to contribute, there's plenty to do. Here's a short todo_ list. .. _GitHub: http://github.com/kennethreitz/python-guide/ .. _todo: https://github.com/kennethreitz/python-guide/blob/master/TODO.rst - -.. include:: ../../AUTHORS.rst \ No newline at end of file diff --git a/docs/scenarios/gui.rst b/docs/scenarios/gui.rst index 8572f7b..037c641 100644 --- a/docs/scenarios/gui.rst +++ b/docs/scenarios/gui.rst @@ -26,12 +26,14 @@ PyObjC WXPython :::::::: + + Install (Stable) ----- +---------------- *Go to http://www.wxpython.org/download.php#stable and download the appropriate package for your OS.* Gtk ::: tk -:: \ No newline at end of file +:: diff --git a/docs/starting/installation.rst b/docs/starting/installation.rst index ace753f..e4890e3 100644 --- a/docs/starting/installation.rst +++ b/docs/starting/installation.rst @@ -65,10 +65,6 @@ If you have homebrew: :: $ easy_install pip - - -To install ``pip``: :: - Hopefully you'll never have to use **easy_install** again. diff --git a/docs/starting/next.rst b/docs/starting/next.rst deleted file mode 100644 index e69de29..0000000 diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index d1c4658..6824665 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -11,6 +11,7 @@ The Basics Code Comments ------------- + Information regarding code comments is taken from PEP 008 (http://www.python.org/dev/peps/pep-0008/). Block comment styling should be used when commenting out multiple lines of code.: :: @@ -34,9 +35,11 @@ Inline comments are used for individual lines and should be used sparingly.: :: Doc Strings ----------- + PEP 257 is the primary reference for docstrings. (http://www.python.org/dev/peps/pep-0257/) -|There are two types of docstrings, one-line and multi-line. Their names should be fairly self explanatory. -|One-line docstrings: :: + +There are two types of docstrings, one-line and multi-line. Their names should be fairly self explanatory. +One-line docstrings: :: def kos_root(): """Return the pathname of the KOS root directory.""" @@ -59,6 +62,7 @@ Multi-line docstrings: :: Sphinx ------ + Sphinx_ is a tool which converts documentation in the :ref:`restructuredtext-ref` markup language into a range of output formats including HTML, LaTeX (for printable PDF versions), manual pages and plain text. .. note:: This Guide is built with Sphinx_ @@ -67,6 +71,7 @@ Sphinx_ is a tool which converts documentation in the :ref:`restructuredtext-ref .. _restructuredtext-ref: + reStructuredText ---------------- @@ -84,4 +89,4 @@ pocco / docco / shocco ---------------------- Ronn ----- \ No newline at end of file +---- From 36e0ea967a13770d7bdd98997e64670696521178 Mon Sep 17 00:00:00 2001 From: Ori Avtalion Date: Wed, 4 Jan 2012 21:27:11 +0200 Subject: [PATCH 51/51] Fix typos, wording --- docs/intro/community.rst | 4 ++-- docs/intro/learning.rst | 2 +- docs/intro/news.rst | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/intro/community.rst b/docs/intro/community.rst index 74b3720..be1176e 100644 --- a/docs/intro/community.rst +++ b/docs/intro/community.rst @@ -19,7 +19,7 @@ The mission of the Python Software Foundation is to promote, protect, and advanc PEPs ---- -PEPs are *Python Enhancement Proposals*. They are define change to Python itself, or the standards around it. +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 `_): @@ -70,4 +70,4 @@ A comprehensive list of conferences is maintained `at pycon.org `_. \ No newline at end of file +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 `_. diff --git a/docs/intro/learning.rst b/docs/intro/learning.rst index 01870fd..ecf3829 100644 --- a/docs/intro/learning.rst +++ b/docs/intro/learning.rst @@ -47,7 +47,7 @@ While exploring the various features available in the python language the author patterns and best practices. The book also includes several case studies which have the reader explore the topics discussed in the book -in greater detail by applying those topics to real-world examples. Case studies include assingments in GUI +in greater detail by applying those topics to real-world examples. Case studies include assignments in GUI and Markov Analysis. `Think Python `_ diff --git a/docs/intro/news.rst b/docs/intro/news.rst index 209ac1a..b24fa93 100644 --- a/docs/intro/news.rst +++ b/docs/intro/news.rst @@ -19,7 +19,7 @@ Python-related news. Python Weekly ~~~~~~~~~~~~~ -Python Weekly is a free weekly newsletter featureing curated news, articles, -new releases, jobs etc related to Python. +Python Weekly is a free weekly newsletter featuring curated news, articles, +new releases, jobs, etc. related to Python. `Python Weekly `_