Skip to content
Browse files

Nuke old docs tree, update other refs to docs files

  • Loading branch information...
1 parent f49d6cd commit 6f8049a9a7c02dc58c48ffb3cda1a9958ed23cf5 @bitprophet bitprophet committed
View
7 CONTRIBUTING.rst
@@ -25,9 +25,10 @@ Patch submission guidelines
which category your change falls in, just ask on IRC or the mailing list --
it's often a judgement call.
* **Make sure documentation is updated** -- at the very least, keep docstrings
- current, and if necessary, update the ReST documentation in ``docs/``. For
- example, new ``env.*`` settings should be added to ``docs/usage/env.rst``.
-* **Add a changelog entry** at the top of ``docs/changelog.rst`` following
+ current, and if necessary, update the ReST documentation in ``sites/docs/``.
+ For example, new ``env.*`` settings should be added to
+ ``sites/docs/usage/env.rst``.
+* **Add a changelog entry** at the top of ``sites/www/changelog.rst`` following
existing entries' styles. Don't forget to attribute yourself if you'd like
credit!
View
2 INSTALL
@@ -1,2 +1,2 @@
For installation help, please see http://fabfile.org/ or (if using a source
-checkout) docs/installation.rst.
+checkout) sites/www/installation.rst.
View
5 MANIFEST.in
@@ -2,8 +2,9 @@ include AUTHORS
include INSTALL
include LICENSE
include README.rst
-recursive-include docs *
-recursive-exclude docs/_build *
+recursive-include sites *
+recursive-exclude sites/docs/_build *
+recursive-exclude sites/www/_build *
include requirements.txt
recursive-include tests *
recursive-exclude tests *.pyc *.pyo
View
88 docs/Makefile
@@ -1,88 +0,0 @@
-# Makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
-SPHINXOPTS =
-SPHINXBUILD = sphinx-build
-PAPER =
-
-# Internal variables.
-PAPEROPT_a4 = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-
-.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
-
-help:
- @echo "Please use \`make <target>' where <target> is one of"
- @echo " html to make standalone HTML files"
- @echo " dirhtml to make HTML files named index.html in directories"
- @echo " pickle to make pickle files"
- @echo " json to make JSON files"
- @echo " htmlhelp to make HTML files and a HTML help project"
- @echo " qthelp to make HTML files and a qthelp project"
- @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
- @echo " changes to make an overview of all changed/added/deprecated items"
- @echo " linkcheck to check all external links for integrity"
- @echo " doctest to run all doctests embedded in the documentation (if enabled)"
-
-clean:
- -rm -rf _build/*
-
-html:
- $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html
- @echo
- @echo "Build finished. The HTML pages are in _build/html."
-
-dirhtml:
- $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) _build/dirhtml
- @echo
- @echo "Build finished. The HTML pages are in _build/dirhtml."
-
-pickle:
- $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle
- @echo
- @echo "Build finished; now you can process the pickle files."
-
-json:
- $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) _build/json
- @echo
- @echo "Build finished; now you can process the JSON files."
-
-htmlhelp:
- $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp
- @echo
- @echo "Build finished; now you can run HTML Help Workshop with the" \
- ".hhp project file in _build/htmlhelp."
-
-qthelp:
- $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) _build/qthelp
- @echo
- @echo "Build finished; now you can run "qcollectiongenerator" with the" \
- ".qhcp project file in _build/qthelp, like this:"
- @echo "# qcollectiongenerator _build/qthelp/Fabric.qhcp"
- @echo "To view the help file:"
- @echo "# assistant -collectionFile _build/qthelp/Fabric.qhc"
-
-latex:
- $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
- @echo
- @echo "Build finished; the LaTeX files are in _build/latex."
- @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
- "run these through (pdf)latex."
-
-changes:
- $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes
- @echo
- @echo "The overview file is in _build/changes."
-
-linkcheck:
- $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck
- @echo
- @echo "Link check complete; look for any errors in the above output " \
- "or in _build/linkcheck/output.txt."
-
-doctest:
- $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) _build/doctest
- @echo "Testing of doctests in the sources finished, look at the " \
- "results in _build/doctest/output.txt."
View
766 docs/_static/rtd.css
@@ -1,766 +0,0 @@
-/*
- * rtd.css
- * ~~~~~~~~~~~~~~~
- *
- * Sphinx stylesheet -- sphinxdoc theme. Originally created by
- * Armin Ronacher for Werkzeug.
- *
- * Customized for ReadTheDocs by Eric Pierce & Eric Holscher
- *
- * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
- */
-
-/* RTD colors
- * light blue: #e8ecef
- * medium blue: #8ca1af
- * dark blue: #465158
- * dark grey: #444444
- *
- * white hover: #d1d9df;
- * medium blue hover: #697983;
- * green highlight: #8ecc4c
- * light blue (project bar): #e8ecef
- */
-
-@import url("basic.css");
-
-/* PAGE LAYOUT -------------------------------------------------------------- */
-
-body {
- font: 100%/1.5 "ff-meta-web-pro-1","ff-meta-web-pro-2",Arial,"Helvetica Neue",sans-serif;
- text-align: center;
- color: black;
- background-color: #465158;
- padding: 0;
- margin: 0;
-}
-
-div.document {
- text-align: left;
- background-color: #e8ecef;
-}
-
-div.bodywrapper {
- background-color: #ffffff;
- border-left: 1px solid #ccc;
- border-bottom: 1px solid #ccc;
- margin: 0 0 0 16em;
-}
-
-div.body {
- margin: 0;
- padding: 0.5em 1.3em;
- max-width: 55em;
- min-width: 20em;
-}
-
-div.related {
- font-size: 1em;
- background-color: #465158;
-}
-
-div.documentwrapper {
- float: left;
- width: 100%;
- background-color: #e8ecef;
-}
-
-
-/* HEADINGS --------------------------------------------------------------- */
-
-h1 {
- margin: 0;
- padding: 0.7em 0 0.3em 0;
- font-size: 1.5em;
- line-height: 1.15;
- color: #111;
- clear: both;
-}
-
-h2 {
- margin: 2em 0 0.2em 0;
- font-size: 1.35em;
- padding: 0;
- color: #465158;
-}
-
-h3 {
- margin: 1em 0 -0.3em 0;
- font-size: 1.2em;
- color: #6c818f;
-}
-
-div.body h1 a, div.body h2 a, div.body h3 a, div.body h4 a, div.body h5 a, div.body h6 a {
- color: black;
-}
-
-h1 a.anchor, h2 a.anchor, h3 a.anchor, h4 a.anchor, h5 a.anchor, h6 a.anchor {
- display: none;
- margin: 0 0 0 0.3em;
- padding: 0 0.2em 0 0.2em;
- color: #aaa !important;
-}
-
-h1:hover a.anchor, h2:hover a.anchor, h3:hover a.anchor, h4:hover a.anchor,
-h5:hover a.anchor, h6:hover a.anchor {
- display: inline;
-}
-
-h1 a.anchor:hover, h2 a.anchor:hover, h3 a.anchor:hover, h4 a.anchor:hover,
-h5 a.anchor:hover, h6 a.anchor:hover {
- color: #777;
- background-color: #eee;
-}
-
-
-/* LINKS ------------------------------------------------------------------ */
-
-/* Normal links get a pseudo-underline */
-a {
- color: #444;
- text-decoration: none;
- border-bottom: 1px solid #ccc;
-}
-
-/* Links in sidebar, TOC, index trees and tables have no underline */
-.sphinxsidebar a,
-.toctree-wrapper a,
-.indextable a,
-#indices-and-tables a {
- color: #444;
- text-decoration: none;
- border-bottom: none;
-}
-
-/* Most links get an underline-effect when hovered */
-a:hover,
-div.toctree-wrapper a:hover,
-.indextable a:hover,
-#indices-and-tables a:hover {
- color: #111;
- text-decoration: none;
- border-bottom: 1px solid #111;
-}
-
-/* Footer links */
-div.footer a {
- color: #86989B;
- text-decoration: none;
- border: none;
-}
-div.footer a:hover {
- color: #a6b8bb;
- text-decoration: underline;
- border: none;
-}
-
-/* Permalink anchor (subtle grey with a red hover) */
-div.body a.headerlink {
- color: #ccc;
- font-size: 1em;
- margin-left: 6px;
- padding: 0 4px 0 4px;
- text-decoration: none;
- border: none;
-}
-div.body a.headerlink:hover {
- color: #c60f0f;
- border: none;
-}
-
-
-/* NAVIGATION BAR --------------------------------------------------------- */
-
-div.related ul {
- height: 2.5em;
-}
-
-div.related ul li {
- margin: 0;
- padding: 0.65em 0;
- float: left;
- display: block;
- color: white; /* For the >> separators */
- font-size: 0.8em;
-}
-
-div.related ul li.right {
- float: right;
- margin-right: 5px;
- color: transparent; /* Hide the | separators */
-}
-
-/* "Breadcrumb" links in nav bar */
-div.related ul li a {
- order: none;
- background-color: inherit;
- font-weight: bold;
- margin: 6px 0 6px 4px;
- line-height: 1.75em;
- color: #ffffff;
- padding: 0.4em 0.8em;
- border: none;
- border-radius: 3px;
-}
-/* previous / next / modules / index links look more like buttons */
-div.related ul li.right a {
- margin: 0.375em 0;
- background-color: #697983;
- text-shadow: 0 1px rgba(0, 0, 0, 0.5);
- border-radius: 3px;
- -webkit-border-radius: 3px;
- -moz-border-radius: 3px;
-}
-/* All navbar links light up as buttons when hovered */
-div.related ul li a:hover {
- background-color: #8ca1af;
- color: #ffffff;
- text-decoration: none;
- border-radius: 3px;
- -webkit-border-radius: 3px;
- -moz-border-radius: 3px;
-}
-/* Take extra precautions for tt within links */
-a tt,
-div.related ul li a tt {
- background: inherit !important;
- color: inherit !important;
-}
-
-
-/* SIDEBAR ---------------------------------------------------------------- */
-
-div.sphinxsidebarwrapper {
- padding: 0;
-}
-
-div.sphinxsidebar {
- margin: 0;
- margin-left: -100%;
- float: left;
- top: 3em;
- left: 0;
- padding: 0 1em;
- width: 14em;
- font-size: 1em;
- text-align: left;
- background-color: #e8ecef;
-}
-
-div.sphinxsidebar img {
- max-width: 12em;
-}
-
-div.sphinxsidebar h3, div.sphinxsidebar h4 {
- margin: 1.2em 0 0.3em 0;
- font-size: 1em;
- padding: 0;
- color: #222222;
- font-family: "ff-meta-web-pro-1", "ff-meta-web-pro-2", "Arial", "Helvetica Neue", sans-serif;
-}
-
-div.sphinxsidebar h3 a {
- color: #444444;
-}
-
-div.sphinxsidebar ul,
-div.sphinxsidebar p {
- margin-top: 0;
- padding-left: 0;
- line-height: 130%;
- background-color: #e8ecef;
-}
-
-/* No bullets for nested lists, but a little extra indentation */
-div.sphinxsidebar ul ul {
- list-style-type: none;
- margin-left: 1.5em;
- padding: 0;
-}
-
-/* A little top/bottom padding to prevent adjacent links' borders
- * from overlapping each other */
-div.sphinxsidebar ul li {
- padding: 1px 0;
-}
-
-/* A little left-padding to make these align with the ULs */
-div.sphinxsidebar p.topless {
- padding-left: 0 0 0 1em;
-}
-
-/* Make these into hidden one-liners */
-div.sphinxsidebar ul li,
-div.sphinxsidebar p.topless {
- white-space: nowrap;
- overflow: hidden;
-}
-/* ...which become visible when hovered */
-div.sphinxsidebar ul li:hover,
-div.sphinxsidebar p.topless:hover {
- overflow: visible;
-}
-
-/* Search text box and "Go" button */
-#searchbox {
- margin-top: 2em;
- margin-bottom: 1em;
- background: #ddd;
- padding: 0.5em;
- border-radius: 6px;
- -moz-border-radius: 6px;
- -webkit-border-radius: 6px;
-}
-#searchbox h3 {
- margin-top: 0;
-}
-
-/* Make search box and button abut and have a border */
-input,
-div.sphinxsidebar input {
- border: 1px solid #999;
- float: left;
-}
-
-/* Search textbox */
-input[type="text"] {
- margin: 0;
- padding: 0 3px;
- height: 20px;
- width: 144px;
- border-top-left-radius: 3px;
- border-bottom-left-radius: 3px;
- -moz-border-radius-topleft: 3px;
- -moz-border-radius-bottomleft: 3px;
- -webkit-border-top-left-radius: 3px;
- -webkit-border-bottom-left-radius: 3px;
-}
-/* Search button */
-input[type="submit"] {
- margin: 0 0 0 -1px; /* -1px prevents a double-border with textbox */
- height: 22px;
- color: #444;
- background-color: #e8ecef;
- padding: 1px 4px;
- font-weight: bold;
- border-top-right-radius: 3px;
- border-bottom-right-radius: 3px;
- -moz-border-radius-topright: 3px;
- -moz-border-radius-bottomright: 3px;
- -webkit-border-top-right-radius: 3px;
- -webkit-border-bottom-right-radius: 3px;
-}
-input[type="submit"]:hover {
- color: #ffffff;
- background-color: #8ecc4c;
-}
-
-div.sphinxsidebar p.searchtip {
- clear: both;
- padding: 0.5em 0 0 0;
- background: #ddd;
- color: #666;
- font-size: 0.9em;
-}
-
-/* Sidebar links are unusual */
-div.sphinxsidebar li a,
-div.sphinxsidebar p a {
- background: #e8ecef; /* In case links overlap main content */
- border-radius: 3px;
- -moz-border-radius: 3px;
- -webkit-border-radius: 3px;
- border: 1px solid transparent; /* To prevent things jumping around on hover */
- padding: 0 5px 0 5px;
-}
-div.sphinxsidebar li a:hover,
-div.sphinxsidebar p a:hover {
- color: #111;
- text-decoration: none;
- border: 1px solid #888;
-}
-
-/* Tweak any link appearing in a heading */
-div.sphinxsidebar h3 a {
-}
-
-
-
-
-/* OTHER STUFF ------------------------------------------------------------ */
-
-cite, code, tt {
- font-family: 'Consolas', 'Deja Vu Sans Mono',
- 'Bitstream Vera Sans Mono', monospace;
- font-size: 0.95em;
- letter-spacing: 0.01em;
-}
-
-tt {
- background-color: #f2f2f2;
- color: #444;
-}
-
-tt.descname, tt.descclassname, tt.xref {
- border: 0;
-}
-
-hr {
- border: 1px solid #abc;
- margin: 2em;
-}
-
-pre, #_fontwidthtest {
- font-family: 'Consolas', 'Deja Vu Sans Mono',
- 'Bitstream Vera Sans Mono', monospace;
- margin: 1em 2em;
- font-size: 0.95em;
- letter-spacing: 0.015em;
- line-height: 120%;
- padding: 0.5em;
- border: 1px solid #ccc;
- background-color: #eee;
- border-radius: 6px;
- -moz-border-radius: 6px;
- -webkit-border-radius: 6px;
-}
-
-pre a {
- color: inherit;
- text-decoration: underline;
-}
-
-td.linenos pre {
- padding: 0.5em 0;
-}
-
-div.quotebar {
- background-color: #f8f8f8;
- max-width: 250px;
- float: right;
- padding: 2px 7px;
- border: 1px solid #ccc;
-}
-
-div.topic {
- background-color: #f8f8f8;
-}
-
-table {
- border-collapse: collapse;
- margin: 0 -0.5em 0 -0.5em;
-}
-
-table td, table th {
- padding: 0.2em 0.5em 0.2em 0.5em;
-}
-
-
-/* ADMONITIONS AND WARNINGS ------------------------------------------------- */
-
-/* Shared by admonitions and warnings */
-div.admonition, div.warning {
- font-size: 0.9em;
- margin: 2em;
- padding: 0;
- /*
- border-radius: 6px;
- -moz-border-radius: 6px;
- -webkit-border-radius: 6px;
- */
-}
-div.admonition p, div.warning p {
- margin: 0.5em 1em 0.5em 1em;
- padding: 0;
-}
-div.admonition pre, div.warning pre {
- margin: 0.4em 1em 0.4em 1em;
-}
-div.admonition p.admonition-title,
-div.warning p.admonition-title {
- margin: 0;
- padding: 0.1em 0 0.1em 0.5em;
- color: white;
- font-weight: bold;
- font-size: 1.1em;
- text-shadow: 0 1px rgba(0, 0, 0, 0.5);
-}
-div.admonition ul, div.admonition ol,
-div.warning ul, div.warning ol {
- margin: 0.1em 0.5em 0.5em 3em;
- padding: 0;
-}
-
-
-/* Admonitions only */
-div.admonition {
- border: 1px solid #609060;
- background-color: #e9ffe9;
-}
-div.admonition p.admonition-title {
- background-color: #70A070;
- border-bottom: 1px solid #609060;
-}
-
-
-/* Warnings only */
-div.warning {
- border: 1px solid #900000;
- background-color: #ffe9e9;
-}
-div.warning p.admonition-title {
- background-color: #b04040;
- border-bottom: 1px solid #900000;
-}
-
-
-
-div.versioninfo {
- margin: 1em 0 0 0;
- border: 1px solid #ccc;
- background-color: #DDEAF0;
- padding: 8px;
- line-height: 1.3em;
- font-size: 0.9em;
-}
-
-.viewcode-back {
- font-family: 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva',
- 'Verdana', sans-serif;
-}
-
-div.viewcode-block:target {
- background-color: #f4debf;
- border-top: 1px solid #ac9;
- border-bottom: 1px solid #ac9;
-}
-
-dl {
- margin: 1em 0 2.5em 0;
-}
-
-/* Highlight target when you click an internal link */
-dt:target {
- background: #ffe080;
-}
-/* Don't highlight whole divs */
-div.highlight {
- background: transparent;
-}
-/* But do highlight spans (so search results can be highlighted) */
-span.highlight {
- background: #ffe080;
-}
-
-div.footer {
- background-color: #465158;
- color: #eeeeee;
- padding: 0 2em 2em 2em;
- clear: both;
- font-size: 0.8em;
- text-align: center;
-}
-
-p {
- margin: 0.8em 0 0.5em 0;
-}
-
-.section p img {
- margin: 1em 2em;
-}
-
-
-/* MOBILE LAYOUT -------------------------------------------------------------- */
-
-@media screen and (max-width: 600px) {
-
- h1, h2, h3, h4, h5 {
- position: relative;
- }
-
- ul {
- padding-left: 1.75em;
- }
-
- div.bodywrapper a.headerlink, #indices-and-tables h1 a {
- color: #e6e6e6;
- font-size: 80%;
- float: right;
- line-height: 1.8;
- position: absolute;
- right: -0.7em;
- visibility: inherit;
- }
-
- div.bodywrapper h1 a.headerlink, #indices-and-tables h1 a {
- line-height: 1.5;
- }
-
- pre {
- font-size: 0.7em;
- overflow: auto;
- word-wrap: break-word;
- white-space: pre-wrap;
- }
-
- div.related ul {
- height: 2.5em;
- padding: 0;
- text-align: left;
- }
-
- div.related ul li {
- clear: both;
- color: #465158;
- padding: 0.2em 0;
- }
-
- div.related ul li:last-child {
- border-bottom: 1px dotted #8ca1af;
- padding-bottom: 0.4em;
- margin-bottom: 1em;
- width: 100%;
- }
-
- div.related ul li a {
- color: #465158;
- padding-right: 0;
- }
-
- div.related ul li a:hover {
- background: inherit;
- color: inherit;
- }
-
- div.related ul li.right {
- clear: none;
- padding: 0.65em 0;
- margin-bottom: 0.5em;
- }
-
- div.related ul li.right a {
- color: #fff;
- padding-right: 0.8em;
- }
-
- div.related ul li.right a:hover {
- background-color: #8ca1af;
- }
-
- div.body {
- clear: both;
- min-width: 0;
- word-wrap: break-word;
- }
-
- div.bodywrapper {
- margin: 0 0 0 0;
- }
-
- div.sphinxsidebar {
- float: none;
- margin: 0;
- width: auto;
- }
-
- div.sphinxsidebar input[type="text"] {
- height: 2em;
- line-height: 2em;
- width: 70%;
- }
-
- div.sphinxsidebar input[type="submit"] {
- height: 2em;
- margin-left: 0.5em;
- width: 20%;
- }
-
- div.sphinxsidebar p.searchtip {
- background: inherit;
- margin-bottom: 1em;
- }
-
- div.sphinxsidebar ul li, div.sphinxsidebar p.topless {
- white-space: normal;
- }
-
- .bodywrapper img {
- display: block;
- margin-left: auto;
- margin-right: auto;
- max-width: 100%;
- }
-
- div.documentwrapper {
- float: none;
- }
-
- div.admonition, div.warning, pre, blockquote {
- margin-left: 0em;
- margin-right: 0em;
- }
-
- .body p img {
- margin: 0;
- }
-
- #searchbox {
- background: transparent;
- }
-
- .related:not(:first-child) li {
- display: none;
- }
-
- .related:not(:first-child) li.right {
- display: block;
- }
-
- div.footer {
- padding: 1em;
- }
-
- .rtd_doc_footer .badge {
- float: none;
- margin: 1em auto;
- position: static;
- }
-
- .rtd_doc_footer .badge.revsys-inline {
- margin-right: auto;
- margin-bottom: 2em;
- }
-
- table.indextable {
- display: block;
- width: auto;
- }
-
- .indextable tr {
- display: block;
- }
-
- .indextable td {
- display: block;
- padding: 0;
- width: auto !important;
- }
-
- .indextable td dt {
- margin: 1em 0;
- }
-
- ul.search {
- margin-left: 0.25em;
- }
-
- ul.search li div.context {
- font-size: 90%;
- line-height: 1.1;
- margin-bottom: 1;
- margin-left: 0;
- }
-
-}
View
33 docs/_templates/layout.html
@@ -1,33 +0,0 @@
-{% extends "!layout.html" %}
-
-{%- block extrahead %}
-{{ super() }}
-<script type="text/javascript">
- var _gaq = _gaq || [];
- _gaq.push(['_setAccount', 'UA-18486793-1']);
- _gaq.push(['_setDomainName', '.fabfile.org']);
- _gaq.push(['_trackPageview']);
-
- (function() {
- var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
- ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
- var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
- })();
-</script>
-
-{% endblock %}
-
-
-{% block sidebarlogo %}
-{{ super() }}
-{% if fabric_tags %}
-<h3>Project Versions</h3>
-<ul id="sidebar_versions">
- {% for tag in fabric_tags %}
- {% if loop.index <= 10 %}
- <li><a href="/en/{{ tag }}/">{{ tag }}</a></li>
- {% endif %}
- {% endfor %}
-</ul>
-{% endif %}
-{% endblock %}
View
5 docs/api/contrib/console.rst
@@ -1,5 +0,0 @@
-Console Output Utilities
-========================
-
-.. automodule:: fabric.contrib.console
- :members:
View
6 docs/api/contrib/django.rst
@@ -1,6 +0,0 @@
-==================
-Django Integration
-==================
-
-.. automodule:: fabric.contrib.django
- :members:
View
6 docs/api/contrib/files.rst
@@ -1,6 +0,0 @@
-=============================
-File and Directory Management
-=============================
-
-.. automodule:: fabric.contrib.files
- :members:
View
6 docs/api/contrib/project.rst
@@ -1,6 +0,0 @@
-=============
-Project Tools
-=============
-
-.. automodule:: fabric.contrib.project
- :members:
View
7 docs/api/core/colors.rst
@@ -1,7 +0,0 @@
-======================
-Color output functions
-======================
-
-.. automodule:: fabric.colors
- :members:
- :undoc-members:
View
6 docs/api/core/context_managers.rst
@@ -1,6 +0,0 @@
-================
-Context Managers
-================
-
-.. automodule:: fabric.context_managers
- :members:
View
6 docs/api/core/decorators.rst
@@ -1,6 +0,0 @@
-==========
-Decorators
-==========
-
-.. automodule:: fabric.decorators
- :members: hosts, roles, runs_once, serial, parallel, task, with_settings
View
6 docs/api/core/docs.rst
@@ -1,6 +0,0 @@
-=====================
-Documentation helpers
-=====================
-
-.. automodule:: fabric.docs
- :members:
View
7 docs/api/core/network.rst
@@ -1,7 +0,0 @@
-=======
-Network
-=======
-
-.. automodule:: fabric.network
-
- .. autofunction:: disconnect_all
View
6 docs/api/core/operations.rst
@@ -1,6 +0,0 @@
-==========
-Operations
-==========
-
-.. automodule:: fabric.operations
- :members:
View
6 docs/api/core/tasks.rst
@@ -1,6 +0,0 @@
-=====
-Tasks
-=====
-
-.. automodule:: fabric.tasks
- :members: Task, WrappedCallableTask, execute
View
6 docs/api/core/utils.rst
@@ -1,6 +0,0 @@
-=====
-Utils
-=====
-
-.. automodule:: fabric.utils
- :members:
View
1,550 docs/changelog.rst
0 additions, 1,550 deletions not shown because the diff is too large. Please use a local Git client to view these changes.
View
238 docs/conf.py
@@ -1,238 +0,0 @@
-# -*- coding: utf-8 -*-
-#
-# Fabric documentation build configuration file, created by
-# sphinx-quickstart on Sat Apr 25 14:53:36 2009.
-#
-# This file is execfile()d with the current directory set to its containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
-from __future__ import with_statement
-import os
-import sys
-import types
-from datetime import datetime
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.append(os.path.abspath('.'))
-
-# -- General configuration -----------------------------------------------------
-
-# 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.autodoc', 'releases']
-
-# 'releases' (changelog) settings
-releases_issue_uri = "https://github.com/fabric/fabric/issues/%s"
-releases_release_uri = "https://github.com/fabric/fabric/tree/%s"
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The suffix of source filenames.
-source_suffix = '.rst'
-
-# The encoding of source files.
-#source_encoding = 'utf-8'
-
-# The master toctree document.
-master_doc = 'index'
-
-# General information about the project.
-project = u'Fabric'
-year = datetime.now().year
-copyright = u'%d, Christian Vest Hansen and Jeffrey E. Forcier' % year
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-
-# Add this checkout's local Fabric module to sys.path. Allows use of
-# fabric.version in here, and ensures that the autodoc stuff also works.
-sys.path.insert(0, os.path.abspath(os.path.join(os.getcwd(), '..')))
-from fabric.version import get_version
-
-# Get version info
-#
-# Branch-only name
-version = get_version('branch')
-# The full human readable version, including alpha/beta/rc tags.
-release = get_version('normal')
-
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#language = None
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-#today = ''
-# Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
-
-# List of documents that shouldn't be included in the build.
-#unused_docs = []
-
-# List of directories, relative to source directory, that shouldn't be searched
-# for source files.
-exclude_trees = ['_build']
-
-# The reST default role (used for this markup: `text`) to use for all documents.
-default_role = 'obj'
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-#add_module_names = True
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-#show_authors = False
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
-# A list of ignored prefixes for module index sorting.
-#modindex_common_prefix = []
-
-
-# -- Options for HTML output ---------------------------------------------------
-
-# The theme to use for HTML and HTML Help pages. Major themes that come with
-# Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'default'
-html_style = 'rtd.css'
-html_context = {}
-
-from fabric.api import local, hide, settings
-with settings(hide('everything'), warn_only=True):
- get_tags = 'git tag | sort -r | egrep "(1\.[^0]+)\.."'
- tag_result = local(get_tags, True)
- if tag_result.succeeded:
- html_context['fabric_tags'] = tag_result.split()
-
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further. For a list of options available for each theme, see the
-# documentation.
-#html_theme_options = {}
-
-# Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
-
-# The name for this set of Sphinx documents. If None, it defaults to
-# "<project> v<release> documentation".
-#html_title = None
-
-# A shorter title for the navigation bar. Default is the same as html_title.
-#html_short_title = None
-
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-#html_logo = None
-
-# The name of an image file (within the static path) to use as favicon of the
-# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-#html_favicon = None
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
-
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-#html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
-
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-#html_additional_pages = {}
-
-# If false, no module index is generated.
-#html_use_modindex = True
-
-# If false, no index is generated.
-#html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-#html_split_index = False
-
-# If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it. The value of this option must be the
-# base URL from which the finished HTML is served.
-#html_use_opensearch = ''
-
-# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = ''
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'Fabricdoc'
-
-
-# -- Options for LaTeX output --------------------------------------------------
-
-# The paper size ('letter' or 'a4').
-#latex_paper_size = 'letter'
-
-# The font size ('10pt', '11pt' or '12pt').
-#latex_font_size = '10pt'
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass [howto/manual]).
-latex_documents = [
- ('index', 'Fabric.tex', u'Fabric Documentation',
- u'Jeff Forcier', 'manual'),
-]
-
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-#latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-#latex_use_parts = False
-
-# Additional stuff for the LaTeX preamble.
-#latex_preamble = ''
-
-# Documents to append as an appendix to all manuals.
-#latex_appendices = []
-
-# If false, no module index is generated.
-#latex_use_modindex = True
-
-
-# Restore decorated functions so that autodoc inspects the right arguments
-def unwrap_decorated_functions():
- from fabric import operations, context_managers
- for module in [context_managers, operations]:
- for name, obj in vars(module).iteritems():
- if (
- # Only function objects - just in case some real object showed
- # up that had .undecorated
- isinstance(obj, types.FunctionType)
- # Has our .undecorated 'cache' of the real object
- and hasattr(obj, 'undecorated')
- ):
- setattr(module, name, obj.undecorated)
-
-unwrap_decorated_functions()
View
206 docs/development.rst
@@ -1,206 +0,0 @@
-===========
-Development
-===========
-
-The Fabric development team is headed by `Jeff Forcier
-<http://bitprophet.org>`_, aka ``bitprophet``. However, dozens of other
-developers pitch in by submitting patches and ideas via `GitHub issues and pull
-requests <https://github.com/fabric/fabric>`_, :ref:`IRC <irc>` or the `mailing
-list <http://lists.nongnu.org/mailman/listinfo/fab-user>`_.
-
-Get the code
-============
-
-Please see the :ref:`source-code-checkouts` section of the :doc:`installation`
-page for details on how to obtain Fabric's source code.
-
-Contributing
-============
-
-There are a number of ways to get involved with Fabric:
-
-* **Use Fabric and send us feedback!** This is both the easiest and arguably
- the most important way to improve the project -- let us know how you
- currently use Fabric and how you want to use it. (Please do try to search the
- `ticket tracker <https://github.com/fabric/fabric/issues>`_ first, though,
- when submitting feature ideas.)
-* **Report bugs.** Pretty much a special case of the previous item: if you
- think you've found a bug in Fabric, check on the `ticket tracker
- <https://github.com/fabric/fabric/issues>`_ to see if anyone's reported it
- yet, and if not -- file a bug! If possible, try to make sure you can
- replicate it repeatedly, and let us know the circumstances (what version of
- Fabric you're using, what platform you're on, and what exactly you were doing
- when the bug cropped up.)
-* **Submit patches or new features.** Make a `Github <https://github.com>`_
- account, `create a fork <http://help.github.com/fork-a-repo/>`_ of `the main
- Fabric repository <https://github.com/fabric/fabric>`_, and `submit a pull
- request <http://help.github.com/send-pull-requests/>`_.
-
-While we may not always reply promptly, we do try to make time eventually to
-inspect all contributions and either incorporate them or explain why we don't
-feel the change is a good fit.
-
-.. include:: ../CONTRIBUTING.rst
-
-Coding style
-------------
-
-Fabric tries hard to honor `PEP-8`_, especially (but not limited to!) the
-following:
-
-* Keep all lines under 80 characters. This goes for the ReST documentation as
- well as code itself.
-
- * Exceptions are made for situations where breaking a long string (such as a
- string being ``print``-ed from source code, or an especially long URL link
- in documentation) would be kind of a pain.
-
-* Typical Python 4-space (soft-tab) indents. No tabs! No 8 space indents! (No
- 2- or 3-space indents, for that matter!)
-* ``CamelCase`` class names, but ``lowercase_underscore_separated`` everything
- else.
-
-.. _PEP-8: http://www.python.org/dev/peps/pep-0008/
-
-Communication
--------------
-
-If a ticket-tracker ticket exists for a given issue, **please** keep all
-communication in that ticket's comments -- for example, when submitting patches
-via Github, it's easier for us if you leave a note in the ticket **instead of**
-sending a Github pull request.
-
-The core devs receive emails for just about any ticket-tracker activity, so
-additional notices via Github or other means only serve to slow things down.
-
-Branching/Repository Layout
-===========================
-
-While Fabric's development methodology isn't set in stone yet, the following
-items detail how we currently organize the Git repository and expect to perform
-merges and so forth. This will be chiefly of interest to those who wish to
-follow a specific Git branch instead of released versions, or to any
-contributors.
-
-* We use a combined 'release and feature branches' methodology, where every
- minor release (e.g. 0.9, 1.0, 1.1, 1.2 etc; see :ref:`releases` below for
- details on versioning) gets a release branch for bugfixes, and big feature
- development is performed in a central ``master`` branch and/or in
- feature-specific feature branches (e.g. a branch for reworking the internals
- to be threadsafe, or one for overhauling task dependencies, etc.)
-* Releases each get their own release branch, e.g. ``0.9``, ``1.0``, ``1.1``
- etc, and from these the actual releases are tagged, e.g. ``0.9.3`` or
- ``1.0.0``.
-* New feature work is typically done in feature branches, whose naming
- convention is ``<ticket number>-<short-description>``. For example, ticket
- #61, which concerned adding ``cd`` support to ``get`` and ``put``, was
- developed in a branch named ``61-add-cd-to-get-put``.
-
- * These branches are not intended for public use, and may be cleaned out of
- the repositories periodically. Ideally, no one feature will be in
- development long enough for its branch to become used in production!
-
-* Completed feature work is merged into the ``master`` branch, and once enough
- new features are done, a new release branch is created and optionally used to
- create prerelease versions for testing -- or simply released as-is.
-* While we try our best not to commit broken code or change APIs without
- warning, as with many other open-source projects we can only have a guarantee
- of stability in the release branches. Only follow ``master`` (or, even worse,
- feature branches!) if you're willing to deal with a little pain.
-* Conversely, because we try to keep release branches relatively stable, you
- may find it easier to use Fabric from a source checkout of a release branch
- instead of manually upgrading to new released versions. This can provide a
- decent middle ground between stability and the ability to get bugfixes or
- backported features easily.
-* The core developers will take care of performing merging/branching on the
- official repositories. Since Git is Git, contributors may of course do
- whatever they wish in their own clones/forks.
-* Bugfixes are to be performed on release branches and then merged into
- ``master`` so that ``master`` is always up-to-date (or nearly so; while it's
- not mandatory to merge after every bugfix, doing so at least daily is a good
- idea.)
-* Feature branches should periodically merge in changes from
- ``master`` so that when it comes time for them to merge back into ``master``
- things aren't quite as painful.
-
-.. _releases:
-
-Releases
-========
-
-Fabric tries to follow open-source standards and conventions in its release
-tagging, including typical version numbers such as 2.0, 1.2.5, or
-1.2b1. Each release will be marked as a tag in the Git repositories, and
-are broken down as follows:
-
-Major
------
-
-Major releases update the first number, e.g. going from 0.9 to 1.0, and
-indicate that the software has reached some very large milestone.
-
-For example, the 1.0 release signified a commitment to a medium to long term
-API and some significant backwards incompatible (compared to the 0.9 series)
-features. Version 2.0 might indicate a rewrite using a new underlying network
-technology or an overhaul to be more object-oriented.
-
-Major releases will often be backwards-incompatible with the previous line of
-development, though this is not a requirement, just a usual happenstance.
-Users should expect to have to make at least some changes to their fabfiles
-when switching between major versions.
-
-Minor
------
-
-Minor releases, such as moving from 1.0 to 1.1, typically mean that one or more
-new, large features has been added. They are also sometimes used to mark off
-the fact that a lot of bug fixes or small feature modifications have occurred
-since the previous minor release. (And, naturally, some of them will involve
-both at the same time.)
-
-These releases are guaranteed to be backwards-compatible with all other
-releases containing the same major version number, so a fabfile that works
-with 1.0 should also work fine with 1.1 or even 1.9.
-
-Bugfix/tertiary
----------------
-
-The third and final part of version numbers, such as the '3' in 1.0.3,
-generally indicate a release containing one or more bugfixes, although minor
-feature modifications may (rarely) occur.
-
-This third number is sometimes omitted for the first major or minor release in
-a series, e.g. 1.2 or 2.0, and in these cases it can be considered an implicit
-zero (e.g. 2.0.0).
-
-.. note::
-
- The 0.9 series of development included more significant feature work than
- is typically found in tertiary releases; from 1.0 onwards a more
- traditional approach, as per the above, is used.
-
-
-Support of older releases
-=========================
-
-Major and minor releases do not mark the end of the previous line or lines of
-development:
-
-* The two most recent minor release branches will continue to receive critical
- bugfixes. For example, if 1.1 were the latest minor release, it and 1.0 would
- get bugfixes, but not 0.9 or earlier; and once 1.2 came out, this window
- would then only extend back to 1.1.
-* Depending on the nature of bugs found and the difficulty in backporting them,
- older release lines may also continue to get bugfixes -- but there's no
- longer a guarantee of any kind. Thus, if a bug were found in 1.1 that
- affected 0.9 and could be easily applied, a new 0.9.x version *might* be
- released.
-* This policy may change in the future to accommodate more branches, depending
- on development speed.
-
-We hope that this policy will allow us to have a rapid minor release cycle (and
-thus keep new features coming out frequently) without causing users to feel too
-much pressure to upgrade right away. At the same time, the backwards
-compatibility guarantee means that users should still feel comfortable
-upgrading to the next minor release in order to stay within this sliding
-support window.
View
234 docs/faq.rst
@@ -1,234 +0,0 @@
-================================
-Frequently Asked Questions (FAQ)
-================================
-
-These are some of the most commonly encountered problems or frequently asked
-questions which we receive from users. They aren't intended as a substitute for
-reading the rest of the documentation, especially the :ref:`usage docs
-<usage-docs>`, so please make sure you check those out if your question is not
-answered here.
-
-
-How do I dynamically set host lists?
-====================================
-
-See :ref:`dynamic-hosts`.
-
-
-How can I run something after my task is done on all hosts?
-===========================================================
-
-See :ref:`leveraging-execute-return-value`.
-
-
-.. _init-scripts-pty:
-
-Init scripts don't work!
-========================
-
-Init-style start/stop/restart scripts (e.g. ``/etc/init.d/apache2 start``)
-sometimes don't like Fabric's allocation of a pseudo-tty, which is active by
-default. In almost all cases, explicitly calling the command in question with
-``pty=False`` works correctly::
-
- sudo("/etc/init.d/apache2 restart", pty=False)
-
-If you have no need for interactive behavior and run into this problem
-frequently, you may want to deactivate pty allocation globally by setting
-:ref:`env.always_use_pty <always-use-pty>` to ``False``.
-
-.. _one-shell-per-command:
-
-My (``cd``/``workon``/``export``/etc) calls don't seem to work!
-===============================================================
-
-While Fabric can be used for many shell-script-like tasks, there's a slightly
-unintuitive catch: each `~fabric.operations.run` or `~fabric.operations.sudo`
-call has its own distinct shell session. This is required in order for Fabric
-to reliably figure out, after your command has run, what its standard out/error
-and return codes were.
-
-Unfortunately, it means that code like the following doesn't behave as you
-might assume::
-
- def deploy():
- run("cd /path/to/application")
- run("./update.sh")
-
-If that were a shell script, the second `~fabric.operations.run` call would
-have executed with a current working directory of ``/path/to/application/`` --
-but because both commands are run in their own distinct session over SSH, it
-actually tries to execute ``$HOME/update.sh`` instead (since your remote home
-directory is the default working directory).
-
-A simple workaround is to make use of shell logic operations such as ``&&``,
-which link multiple expressions together (provided the left hand side executed
-without error) like so::
-
- def deploy():
- run("cd /path/to/application && ./update.sh")
-
-Fabric provides a convenient shortcut for this specific use case, in fact:
-`~fabric.context_managers.cd`. There is also `~fabric.context_managers.prefix`
-for arbitrary prefix commands.
-
-.. note::
- You might also get away with an absolute path and skip directory changing
- altogether::
-
- def deploy():
- run("/path/to/application/update.sh")
-
- However, this requires that the command in question makes no assumptions
- about your current working directory!
-
-
-How do I use ``su`` to run commands as another user?
-====================================================
-
-This is a special case of :ref:`one-shell-per-command`. As that FAQ explains,
-commands like ``su`` which are 'stateful' do not work well in Fabric, so
-workarounds must be used.
-
-In the case of running commands as a user distinct from the login user, you
-have two options:
-
-#. Use `~fabric.operations.sudo` with its ``user=`` kwarg, e.g.
- ``sudo("command", user="otheruser")``. If you want to factor the ``user``
- part out of a bunch of commands, use `~fabric.context_managers.settings` to
- set ``env.sudo_user``::
-
- with settings(sudo_user="otheruser"):
- sudo("command 1")
- sudo("command 2")
- ...
-
-#. If your target system cannot use ``sudo`` for some reason, you can still use
- ``su``, but you need to invoke it in a non-interactive fashion by telling it
- to run a specific command instead of opening a shell. Typically this is the
- ``-c`` flag, e.g. ``su otheruser -c "command"``.
-
- To run multiple commands in the same ``su -c`` "wrapper", you could e.g.
- write a wrapper function around `~fabric.operations.run`::
-
- def run_su(command, user="otheruser"):
- return run('su %s -c "%s"' % (user, command))
-
-
-Why do I sometimes see ``err: stdin: is not a tty``?
-====================================================
-
-This message is typically generated by programs such as ``biff`` or ``mesg``
-lurking within your remote user's ``.profile`` or ``.bashrc`` files (or any
-other such files, including system-wide ones.) Fabric's default mode of
-operation involves executing the Bash shell in "login mode", which causes these
-files to be executed.
-
-Because Fabric also doesn't bother asking the remote end for a tty by default
-(as it's not usually necessary) programs fired within your startup files, which
-expect a tty to be present, will complain -- and thus, stderr output about
-"stdin is not a tty" or similar.
-
-There are multiple ways to deal with this problem:
-
-* Find and remove or comment out the offending program call. If the program was
- not added by you on purpose and is simply a legacy of the operating system,
- this may be safe to do, and is the simplest approach.
-* Override ``env.shell`` to remove the ``-l`` flag. This should tell Bash not
- to load your startup files. If you don't depend on the contents of your
- startup files (such as aliases or whatnot) this may be a good solution.
-* Pass ``pty=True`` to `run` or `sudo`, which will force allocation of a
- pseudo-tty on the remote end, and hopefully cause the offending program to be
- less cranky.
-
-
-.. _faq-daemonize:
-
-Why can't I run programs in the background with ``&``? It makes Fabric hang.
-============================================================================
-
-Because Fabric executes a shell on the remote end for each invocation of
-``run`` or ``sudo`` (:ref:`see also <one-shell-per-command>`), backgrounding a
-process via the shell will not work as expected. Backgrounded processes may
-still prevent the calling shell from exiting until they stop running, and this
-in turn prevents Fabric from continuing on with its own execution.
-
-The key to fixing this is to ensure that your process' standard pipes are all
-disassociated from the calling shell, which may be done in a number of ways
-(listed in order of robustness):
-
-* Use a pre-existing daemonization technique if one exists for the program at
- hand -- for example, calling an init script instead of directly invoking a
- server binary.
-
- * Or leverage a process manager such as ``supervisord``, ``upstart`` or
- ``systemd`` - such tools let you define what it means to "run" one of
- your background processes, then issue init-script-like
- start/stop/restart/status commands. They offer many advantages over
- classic init scripts as well.
-
-* Use ``tmux``, ``screen`` or ``dtach`` to fully detach the process from the
- running shell; these tools have the benefit of allowing you to reattach to
- the process later on if needed (though they are more ad-hoc than
- ``supervisord``-like tools).
-* Run the program under ``nohup`` or similar "in-shell" tools - note that this
- approach has seen limited success for most users.
-
-
-.. _faq-bash:
-
-My remote system doesn't have ``bash`` installed by default, do I need to install ``bash``?
-===========================================================================================
-
-While Fabric is written with ``bash`` in mind, it's not an absolute
-requirement. Simply change :ref:`env.shell <shell>` to call your desired shell, and
-include an argument similar to ``bash``'s ``-c`` argument, which allows us to
-build shell commands of the form::
-
- /bin/bash -l -c "<command string here>"
-
-where ``/bin/bash -l -c`` is the default value of :ref:`env.shell <shell>`.
-
-.. note::
-
- The ``-l`` argument specifies a login shell and is not absolutely
- required, merely convenient in many situations. Some shells lack the option
- entirely and it may be safely omitted in such cases.
-
-A relatively safe baseline is to call ``/bin/sh``, which may call the original
-``sh`` binary, or (on some systems) ``csh``, and give it the ``-c``
-argument, like so::
-
- from fabric.api import env
-
- env.shell = "/bin/sh -c"
-
-This has been shown to work on FreeBSD and may work on other systems as well.
-
-
-I'm sometimes incorrectly asked for a passphrase instead of a password.
-=======================================================================
-
-Due to a bug of sorts in our SSH layer, it's not currently possible for Fabric
-to always accurately detect the type of authentication needed. We have to try
-and guess whether we're being asked for a private key passphrase or a remote
-server password, and in some cases our guess ends up being wrong.
-
-The most common such situation is where you, the local user, appear to have an
-SSH keychain agent running, but the remote server is not able to honor your SSH
-key, e.g. you haven't yet transferred the public key over or are using an
-incorrect username. In this situation, Fabric will prompt you with "Please
-enter passphrase for private key", but the text you enter is actually being
-sent to the remote end's password authentication.
-
-We hope to address this in future releases by modifying a fork of the
-aforementioned SSH library.
-
-
-Is Fabric thread-safe?
-======================
-
-Currently, no, it's not -- the present version of Fabric relies heavily on
-shared state in order to keep the codebase simple. However, there are definite
-plans to update its internals so that Fabric may be either threaded or
-otherwise parallelized so your tasks can run on multiple servers concurrently.
View
205 docs/index.rst
@@ -1,205 +0,0 @@
-======
-Fabric
-======
-
-About
-=====
-
-.. include:: ../README.rst
-
-
-Installation
-============
-
-Stable releases of Fabric are best installed via ``pip`` or ``easy_install``;
-or you may download TGZ or ZIP source archives from a couple of official
-locations. Detailed instructions and links may be found on the
-:doc:`installation` page.
-
-We recommend using the latest stable version of Fabric; releases are made often
-to prevent any large gaps in functionality between the latest stable release
-and the development version.
-
-However, if you want to live on the edge, you can pull down the source code
-from our Git repository, or fork us on Github. The :doc:`installation` page has
-details for how to access the source code.
-
-.. warning::
-
- If you install Fabric from Git, you will need to install its dependency
- Paramiko from Git as well. See :doc:`the installation docs <installation>`
- for details.
-
-
-Development
-===========
-
-Any hackers interested in improving Fabric (or even users interested in how
-Fabric is put together or released) please see the :doc:`development` page. It
-contains comprehensive info on contributing, repository layout, our release
-strategy, and more.
-
-
-.. _documentation-index:
-
-Documentation
-=============
-
-Please note that all documentation is currently written with Python 2.5 users
-in mind, but with an eye for eventual Python 3.x compatibility. This leads to
-the following patterns that may throw off readers used to Python 2.4 or who
-have already upgraded to Python 2.6/2.7:
-
-* ``from __future__ import with_statement``: a "future import" required to
- use the ``with`` statement in Python 2.5 -- a feature you'll be using
- frequently. Python 2.6+ users don't need to do this.
-* ``<true_value> if <expression> else <false_value>``: Python's relatively new
- ternary statement, available in 2.5 and newer. Python 2.4 and older used to
- fake this with ``<expression> and <true_value> or <false_value>`` (which
- isn't quite the same thing and has some logical loopholes.)
-* ``print(<expression>)`` instead of ``print <expression>``: We use the
- ``print`` statement's optional parentheses where possible, in order to be
- more compatible with Python 3.x (in which ``print`` becomes a function.)
-
-.. toctree::
- :hidden:
-
- tutorial
- installation
- development
- faq
- troubleshooting
- roadmap
-
-Tutorial
---------
-
-For new users, and/or for an overview of Fabric's basic functionality, please
-see the :doc:`tutorial`. The rest of the documentation will assume you're
-at least passingly familiar with the material contained within.
-
-.. _usage-docs:
-
-Usage documentation
--------------------
-
-The following list contains all major sections of Fabric's prose (non-API)
-documentation, which expands upon the concepts outlined in the
-:doc:`tutorial` and also covers advanced topics.
-
-.. toctree::
- :maxdepth: 2
- :glob:
-
- usage/*
-
-.. _faq:
-
-FAQ
----
-
-Some frequently encountered questions, coupled with answers/solutions/excuses,
-may be found on the :doc:`faq` page.
-
-Troubleshooting
----------------
-
-Before asking for help or filing a bug, make sure you've read our
-:doc:`document on troubleshooting <troubleshooting>`.
-
-.. _api_docs:
-
-API documentation
------------------
-
-Fabric maintains two sets of API documentation, autogenerated from the source
-code's docstrings (which are typically very thorough.)
-
-.. _core-api:
-
-Core API
-~~~~~~~~
-
-The **core** API is loosely defined as those functions, classes and methods
-which form the basic building blocks of Fabric (such as
-`~fabric.operations.run` and `~fabric.operations.sudo`) upon which everything
-else (the below "contrib" section, and user fabfiles) builds.
-
-.. toctree::
- :maxdepth: 1
- :glob:
-
- api/core/*
-
-.. _contrib-api:
-
-Contrib API
-~~~~~~~~~~~
-
-Fabric's **contrib** package contains commonly useful tools (often merged in
-from user fabfiles) for tasks such as user I/O, modifying remote files, and so
-forth. While the core API is likely to remain small and relatively unchanged
-over time, this contrib section will grow and evolve (while trying to remain
-backwards-compatible) as more use-cases are solved and added.
-
-.. toctree::
- :maxdepth: 1
- :glob:
-
- api/contrib/*
-
-
-Changelog
----------
-
-Please see :doc:`the changelog </changelog>`.
-
-
-Roadmap
--------
-
-Please see :doc:`the roadmap </roadmap>`.
-
-
-Getting help
-============
-
-If you've scoured the :ref:`prose <usage-docs>` and :ref:`API <api_docs>`
-documentation and still can't find an answer to your question, below are
-various support resources that should help. We do request that you do at least
-skim the documentation before posting tickets or mailing list questions,
-however!
-
-Mailing list
-------------
-
-The best way to get help with using Fabric is via the `fab-user mailing list
-<http://lists.nongnu.org/mailman/listinfo/fab-user>`_ (currently hosted at
-``nongnu.org``.) The Fabric developers do their best to reply promptly, and the
-list contains an active community of other Fabric users and contributors as
-well.
-
-Twitter
--------
-
-Fabric has an official Twitter account, `@pyfabric
-<http://twitter.com/pyfabric>`_, which is used for announcements and occasional
-related news tidbits (e.g. "Hey, check out this neat article on Fabric!").
-
-.. _bugs:
-
-Bugs/ticket tracker
--------------------
-
-To file new bugs or search existing ones, you may visit Fabric's `Github Issues
-<https://github.com/fabric/fabric/issues>`_ page. This does require a (free, easy to set up) Github account.
-
-.. _irc:
-
-IRC
----
-
-We maintain a semi-official IRC channel at ``#fabric`` on Freenode
-(``irc://irc.freenode.net``) where the developers and other users may be found.
-As always with IRC, we can't promise immediate responses, but some folks keep
-logs of the channel and will try to get back to you when they can.
View
247 docs/installation.rst
@@ -1,247 +0,0 @@
-============
-Installation
-============
-
-Fabric is best installed via `pip <http://pip.openplans.org>`_ (highly
-recommended) or `easy_install
-<http://wiki.python.org/moin/CheeseShopTutorial>`_ (older, but still works
-fine), e.g.::
-
- $ pip install fabric
-
-You may also opt to use your operating system's package manager; the package is
-typically called ``fabric`` or ``python-fabric``. E.g.::
-
- $ sudo apt-get install fabric
-
-Advanced users wanting to install a development version may use ``pip`` to grab
-the latest master branch (as well as the dev version of the Paramiko
-dependency)::
-
- $ pip install paramiko==dev
- $ pip install fabric==dev
-
-Or, to install an editable version for debugging/hacking, execute ``pip install
--e .`` (or ``python setup.py install``) inside a :ref:`downloaded <downloads>`
-or :ref:`cloned <source-code-checkouts>` copy of the source code.
-
-.. warning::
-
- Any development installs of Fabric (whether via ``==dev`` or ``install
- -e``) require the development version of Paramiko to be installed
- beforehand, or Fabric's installation may fail.
-
-
-Dependencies
-============
-
-In order for Fabric's installation to succeed, you will need four primary pieces of software:
-
-* the Python programming language;
-* the ``setuptools`` packaging/installation library;
-* the Python ``paramiko`` SSH2 library;
-* and ``paramiko``'s dependency, the PyCrypto cryptography library.
-
-and, if using the :doc:`parallel execution mode </usage/parallel>`:
-
-* the `multiprocessing`_ library.
-
-Please read on for important details on each dependency -- there are a few
-gotchas.
-
-Python
-------
-
-Fabric requires `Python <http://python.org>`_ version 2.5 or 2.6. Some caveats
-and notes about other Python versions:
-
-* We are not planning on supporting **Python 2.4** given its age and the number
- of useful tools in Python 2.5 such as context managers and new modules.
- That said, the actual amount of 2.5-specific functionality is not
- prohibitively large, and we would link to -- but not support -- a third-party
- 2.4-compatible fork. (No such fork exists at this time, to our knowledge.)
-* Fabric has not yet been tested on **Python 3.x** and is thus likely to be
- incompatible with that line of development. However, we try to be at least
- somewhat forward-looking (e.g. using ``print()`` instead of ``print``) and
- will definitely be porting to 3.x in the future once our dependencies do.
-
-setuptools
-----------
-
-`Setuptools`_ comes with some Python installations by default; if yours doesn't,
-you'll need to grab it. In such situations it's typically packaged as
-``python-setuptools``, ``py25-setuptools`` or similar. Fabric may drop its
-setuptools dependency in the future, or include alternative support for the
-`Distribute`_ project, but for now setuptools is required for installation.
-
-.. _setuptools: http://pypi.python.org/pypi/setuptools
-.. _Distribute: http://pypi.python.org/pypi/distribute
-
-PyCrypto
---------
-
-`PyCrypto <https://www.dlitz.net/software/pycrypto/>`_ provides the low-level
-(C-based) encryption algorithms used to run SSH, and is thus required by our
-SSH library. There are a couple gotchas associated with installing PyCrypto:
-its compatibility with Python's package tools, and the fact that it is a
-C-based extension.
-
-.. _pycrypto-and-pip:
-
-Package tools
-~~~~~~~~~~~~~
-
-We strongly recommend using ``pip`` to install Fabric as it is newer and
-generally better than ``easy_install``. However, a combination of bugs in
-specific versions of Python, ``pip`` and PyCrypto can prevent installation of
-PyCrypto. Specifically:
-
-* Python = 2.5.x
-* PyCrypto >= 2.1 (which is required to run Fabric >= 1.3)
-* ``pip`` < 0.8.1
-
-When all three criteria are met, you may encounter ``No such file or
-directory`` IOErrors when trying to ``pip install Fabric`` or ``pip install
-PyCrypto``.
-
-The fix is simply to make sure at least one of the above criteria is not met,
-by doing the following (in order of preference):
-
-* Upgrade to ``pip`` 0.8.1 or above, e.g. by running ``pip install -U pip``.
-* Upgrade to Python 2.6 or above.
-* Downgrade to Fabric 1.2.x, which does not require PyCrypto >= 2.1, and
- install PyCrypto 2.0.1 (the oldest version on PyPI which works with Fabric
- 1.2.)
-
-
-C extension
-~~~~~~~~~~~
-
-Unless you are installing from a precompiled source such as a Debian apt
-repository or RedHat RPM, or using :ref:`pypm <pypm>`, you will also need the
-ability to build Python C-based modules from source in order to install
-PyCrypto. Users on **Unix-based platforms** such as Ubuntu or Mac OS X will
-need the traditional C build toolchain installed (e.g. Developer Tools / XCode
-Tools on the Mac, or the ``build-essential`` package on Ubuntu or Debian Linux
--- basically, anything with ``gcc``, ``make`` and so forth) as well as the
-Python development libraries, often named ``python-dev`` or similar.
-
-For **Windows** users we recommend using :ref:`pypm`, installing a C
-development environment such as `Cygwin <http://cygwin.com>`_ or obtaining a
-precompiled Win32 PyCrypto package from `voidspace's Python modules page
-<http://www.voidspace.org.uk/python/modules.shtml#pycrypto>`_.
-
-.. note::
- Some Windows users whose Python is 64-bit have found that the PyCrypto
- dependency ``winrandom`` may not install properly, leading to ImportErrors.
- In this scenario, you'll probably need to compile ``winrandom`` yourself
- via e.g. MS Visual Studio. See :issue:`194` for info.
-
-
-``multiprocessing``
--------------------
-
-An optional dependency, the ``multiprocessing`` library is included in Python's
-standard library in version 2.6 and higher. If you're using Python 2.5 and want
-to make use of Fabric's :doc:`parallel execution features </usage/parallel>`
-you'll need to install it manually; the recommended route, as usual, is via
-``pip``. Please see the `multiprocessing PyPI page
-<http://pypi.python.org/pypi/multiprocessing/>`_ for details.
-
-
-.. warning::
- Early versions of Python 2.6 (in our testing, 2.6.0 through 2.6.2) ship
- with a buggy ``multiprocessing`` module that appears to cause Fabric to
- hang at the end of sessions involving large numbers of concurrent hosts.
- If you encounter this problem, either use :ref:`env.pool_size / -z
- <pool-size>` to limit the amount of concurrency, or upgrade to Python
- >=2.6.3.
-
- Python 2.5 is unaffected, as it requires the PyPI version of
- ``multiprocessing``, which is newer than that shipped with Python <2.6.3.
-
-Development dependencies
-------------------------
-
-If you are interested in doing development work on Fabric (or even just running
-the test suite), you may also need to install some or all of the following
-packages:
-
-* `git <http://git-scm.com>`_ and `Mercurial`_, in order to obtain some of the
- other dependencies below;
-* `Nose <https://github.com/nose-devs/nose>`_
-* `Coverage <http://nedbatchelder.com/code/modules/coverage.html>`_
-* `PyLint <http://www.logilab.org/857>`_
-* `Fudge <http://farmdev.com/projects/fudge/index.html>`_
-* `Sphinx <http://sphinx.pocoo.org/>`_
-
-For an up-to-date list of exact testing/development requirements, including
-version numbers, please see the ``requirements.txt`` file included with the
-source distribution. This file is intended to be used with ``pip``, e.g. ``pip
-install -r requirements.txt``.
-
-.. _Mercurial: http://mercurial.selenic.com/wiki/
-
-
-.. _downloads:
-
-Downloads
-=========
-
-To obtain a tar.gz or zip archive of the Fabric source code, you may visit
-`Fabric's PyPI page <http://pypi.python.org/pypi/Fabric>`_, which offers manual
-downloads in addition to being the entry point for ``pip`` and
-``easy-install``.
-
-
-.. _source-code-checkouts:
-
-Source code checkouts
-=====================
-
-The Fabric developers manage the project's source code with the `Git
-<http://git-scm.com>`_ DVCS. To follow Fabric's development via Git instead of
-downloading official releases, you have the following options:
-
-* Clone the canonical repository straight from `the Fabric organization's
- repository on Github <https://github.com/fabric/fabric>`_,
- ``git://github.com/fabric/fabric.git``
-* Make your own fork of the Github repository by making a Github account,
- visiting `fabric/fabric <http://github.com/fabric/fabric>`_ and clicking the
- "fork" button.
-
-.. note::
-
- If you've obtained the Fabric source via source control and plan on
- updating your checkout in the future, we highly suggest using ``python
- setup.py develop`` instead -- it will use symbolic links instead of file
- copies, ensuring that imports of the library or use of the command-line
- tool will always refer to your checkout.
-
-For information on the hows and whys of Fabric development, including which
-branches may be of interest and how you can help out, please see the
-:doc:`development` page.
-
-
-.. _pypm:
-
-ActivePython and PyPM
-=====================
-
-Windows users who already have ActiveState's `ActivePython
-<http://www.activestate.com/activepython/downloads>`_ distribution installed
-may find Fabric is best installed with `its package manager, PyPM
-<http://code.activestate.com/pypm/>`_. Below is example output from an
-installation of Fabric via ``pypm``::
-
- C:\> pypm install fabric
- The following packages will be installed into "%APPDATA%\Python" (2.7):
- paramiko-1.7.8 pycrypto-2.4 fabric-1.3.0
- Get: [pypm-free.activestate.com] fabric 1.3.0
- Get: [pypm-free.activestate.com] paramiko 1.7.8
- Get: [pypm-free.activestate.com] pycrypto 2.4
- Installing paramiko-1.7.8
- Installing pycrypto-2.4
- Installing fabric-1.3.0
- Fixing script %APPDATA%\Python\Scripts\fab-script.py
- C:\>
View
61 docs/roadmap.rst
@@ -1,61 +0,0 @@
-===================
-Development roadmap
-===================
-
-This document outlines Fabric's intended development path. Please make sure
-you're reading `the latest version
-<http://docs.fabfile.org/en/latest/roadmap.html>`_ of this document!
-
-.. warning::
- This information is subject to change without warning, and should not be
- used as a basis for any life- or career-altering decisions!
-
-Fabric 1.x
-==========
-
-Fabric 1.x, while not end-of-life'd, has reached a tipping point regarding
-internal tech debt & ability to make significant improvements without harming
-backwards compatibility.
-
-As such, future 1.x releases (**1.6** onwards) will emphasize small-to-medium
-features (new features not requiring major overhauls of the internals) and
-bugfixes.
-
-Invoke, Fabric 2.x and Patchwork
-================================
-
-While 1.x moves on as above, we are working on a reimagined 2.x version of the
-tool, and plan to:
-
-* Finish and release `the Invoke tool/library
- <https://github.com/pyinvoke/invoke>`_ (see also :issue:`565`), which is a
- revamped and standalone version of Fabric's task running components.
-
- * Initially it will be basic, matching Fabric's current functionality, but
- with a cleaner base to build on.
- * Said cleaner base then gives us a jumping-off point for new task-oriented
- features such as before/after hooks / call chains, task collections,
- improved namespacing and so forth.
-
-* Start putting together Fabric 2.0, a partly/mostly rewritten Fabric core:
-
- * Leverage Invoke for task running, which will leave Fabric itself much
- more library oriented.
- * Implement object-oriented hosts/host lists and all the fun stuff that
- provides (e.g. no more hacky host string and unintuitive env var
- manipulation.)
- * No (or optional & non-default) shared state.
- * Any other core overhauls difficult to do in a backwards compatible
- fashion.
- * `Current issue list
- <https://github.com/fabric/fabric/issues?labels=2.x>`_
-
-* Spin off ``fabric.contrib.*`` into a standalone "super-Fabric" (as in, "above Fabric") library, `Patchwork <https://github.com/fabric/patchwork>`_.
-
- * This lets core "execute commands on hosts" functionality iterate
- separately from "commonly useful shortcuts using Fabric core".
- * Lots of preliminary work & prior-art scanning has been done in
- :issue:`461`.
- * A public-but-alpha codebase for Patchwork exists as we think about the
- API, and is currently based on Fabric 1.x. It will likely be Fabric 2.x
- based by the time it is stable.
View
52 docs/troubleshooting.rst
@@ -1,52 +0,0 @@
-===============
-Troubleshooting
-===============
-
-Stuck? Having a problem? Here are the steps to try before you submit a bug
-report.
-
-* **Make sure you're on the latest version.** If you're not on the most recent
- version, your problem may have been solved already! Upgrading is always the
- best first step.
-* **Try older versions.** If you're already *on* the latest Fabric, try rolling
- back a few minor versions (e.g. if on 1.7, try Fabric 1.5 or 1.6) and see if
- the problem goes away. This will help the devs narrow down when the problem
- first arose in the commit log.
-* **Try switching up your Paramiko.** Fabric relies heavily on the Paramiko
- library for its SSH functionality, so try applying the above two steps to
- your Paramiko install as well.
-
- .. note::
- Fabric versions sometimes have different Paramiko dependencies - so to
- try older Paramikos you may need to downgrade Fabric as well.
-
-* **Make sure Fabric is really the problem.** If your problem is in the
- behavior or output of a remote command, try recreating it without Fabric
- involved:
-
- * Run Fabric with ``--show=debug`` and look for the ``run:`` or ``sudo:``
- line about the command in question. Try running that exact command,
- including any ``/bin/bash`` wrapper, remotely and see what happens. This
- may find problems related to the bash or sudo wrappers.
- * Execute the command (both the normal version, and the 'unwrapped' version
- seen via ``--show=debug``) from your local workstation using ``ssh``,
- e.g.::
-
- $ ssh -t mytarget "my command"
-
- The ``-t`` flag matches Fabric's default behavior of enabling a PTY
- remotely. This helps identify apps that behave poorly when run in a
- non-shell-spawned PTY.
-
-* **Enable Paramiko-level debug logging.** If your issue is in the lower level
- Paramiko library, it can help us to see the debug output Paramiko prints. At
- top level in your fabfile, add the following::
-
- import logging
- logging.basicConfig(level=logging.DEBUG)
-
- This should start printing Paramiko's debug statements to your standard error
- stream. (Feel free to add more logging kwargs to ``basicConfig()`` such as
- ``filename='/path/to/a/file'`` if you like.)
-
- Then submit this info to anybody helping you on IRC or in your bug report.
View
468 docs/tutorial.rst
@@ -1,468 +0,0 @@
-=====================
-Overview and Tutorial
-=====================
-
-Welcome to Fabric!
-
-This document is a whirlwind tour of Fabric's features and a quick guide to its
-use. Additional documentation (which is linked to throughout) can be found in
-the :ref:`usage documentation <usage-docs>` -- please make sure to check it out.
-
-
-What is Fabric?
-===============
-
-As the ``README`` says:
-
- .. include:: ../README.rst
- :end-before: It provides
-
-More specifically, Fabric is:
-
-* A tool that lets you execute **arbitrary Python functions** via the **command
- line**;
-* A library of subroutines (built on top of a lower-level library) to make
- executing shell commands over SSH **easy** and **Pythonic**.
-
-Naturally, most users combine these two things, using Fabric to write and
-execute Python functions, or **tasks**, to automate interactions with remote
-servers. Let's take a look.
-
-
-Hello, ``fab``
-==============
-
-This wouldn't be a proper tutorial without "the usual"::
-
- def hello():
- print("Hello world!")
-
-Placed in a Python module file named ``fabfile.py`` in your current working
-directory, that ``hello`` function can be executed with the ``fab`` tool
-(installed as part of Fabric) and does just what you'd expect::
-
- $ fab hello
- Hello world!
-
- Done.
-
-That's all there is to it. This functionality allows Fabric to be used as a
-(very) basic build tool even without importing any of its API.
-
-.. note::
-
- The ``fab`` tool simply imports your fabfile and executes the function or
- functions you instruct it to. There's nothing magic about it -- anything
- you can do in a normal Python script can be done in a fabfile!
-
-.. seealso:: :ref:`execution-strategy`, :doc:`/usage/tasks`, :doc:`/usage/fab`
-
-
-Task arguments
-==============
-
-It's often useful to pass runtime parameters into your tasks, just as you might
-during regular Python programming. Fabric has basic support for this using a
-shell-compatible notation: ``<task name>:<arg>,<kwarg>=<value>,...``. It's
-contrived, but let's extend the above example to say hello to you personally::
-
- def hello(name="world"):
-