======
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.
