@@ -1,24 +1,21 @@ Fabric is a Python library and command-line tool designed to streamline -deploying applications or performing system administration tasks via the SSH -protocol. It provides tools for running arbitrary shell commands (either as a -normal login user, or via ``sudo``), uploading and downloading files, and so -forth. +deploying applications or performing system administration tasks via SSH. -Typical use involves defining a "fabfile" (a Python module) containing one or -more functions or tasks which may then be executed by the ``fab`` command-line -tool. For example, here's a small (but complete) ``fabfile.py`` containing a -single task:: +It provides a basic suite of operations for executing local or remote shell +commands (normally or via ``sudo``) and uploading/downloading files, as well as +auxiliary functionality such as prompting the running user for input, or +aborting execution. + +Typical use involves creating a Python module containing one or more functions, +then executing them via the ``fab`` command-line tool. Below is a small but +complete "fabfile" containing a single task:: from fabric.api import run def host_type(): - """ - Prints host type (via ``uname -s``) for a remote host. - """ run('uname -s') -Executing this on an arbitrary server or list of servers is simple (below, -we're using an ssh-agent, and so there are no password prompts):: +Once a task is defined, it may be run on one or more servers, like so:: $ fab -H localhost,linuxbox host_type [localhost] run: uname -s @@ -30,11 +27,7 @@ we're using an ssh-agent, and so there are no password prompts):: Disconnecting from localhost... done. Disconnecting from linuxbox... done. -Fabric provides extra functionality related to this mode of use, such as -prompting for user input, ensuring certain variables are present in order for -tasks to run, and specifying which host or hosts a specific task connects to -by default. - -Fabric may also be used as a standalone library, so that other Python programs -needing a simple but powerful API on top of SSH or SCP may import and utilize -specific pieces of functionality. +In addition to use via the ``fab`` fool, Fabric's components may be imported +into other Python code, providing a Pythonic interface to the SSH protocol +suite at a higher level than that provided by e.g. Paramiko (which +Fabric itself leverages.) README @@ -2,19 +2,6 @@ Fabric ====== -Status -====== - -Fabric 0.9 is now in beta, meaning that its behavior and feature set are -effectively frozen and should not change much, if at all, between now and final -release. Please try out the latest beta release and submit any bugs you find -(see :ref:`bugs` below.) - -While behavior and API are stable, **expect this documentation to be updated and -expanded significantly before the beta period is over**. We plan to add more -examples and more explanatory text on top of the existing API documentation, as -well as adding more prose (non-API) documentation concerning usage and design. - About ===== @@ -25,116 +12,119 @@ About Installation ===================== -Latest stable version ---------------------- +.. warning:: + + Fabric's primary dependency, Paramiko, has a severe bug in its latest + version. Please see the :doc:`installation` page for more details before + using ``easy_install`` or ``pip`` to install Fabric! Stable releases of Fabric are best installed via ``easy_install`` or ``pip``; 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. -Development version -------------------- - -We recommend using the stable version of Fabric; releases are made often to -prevent any large gaps in functionality between the latest stable release and -the development version. +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 latest source -code from our Git repository, or fork us on Github. Please see the -:doc:`development` page for details. +code from our Git repository, or fork us on Github. The :doc:`installation` +page has details for how to access the source code; there is also a +documentation section on :doc:`development` with important information about +Fabric's development process. -Getting help -============ - -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. - -.. _bugs: - -Bugs ----- - -To file new bugs or search existing ones, you may visit Fabric's `Redmine -<http://redmine.org>`_ instance, located at `code.fabfile.org -<http://code.fabfile.org>`_. Anonymous users can currently post new tickets and -comments, but the system may be locked down in the future to prevent spam, so -we highly recommend registering an account. +Documentation +============= -Wiki ----- +Tutorial +-------- -There is an official Fabric wiki reachable at `wiki.fabfile.org -<http://wiki.fabfile.org>`_, although as of this writing its usage patterns -are still being worked out. There is a `TodoList page -<http://wiki.fabfile.org/TodoList>`_ which may also be used to submit bug -reports, as an alternative to sending email. The wiki is currently locked due -to spammers, so you'll need to register an account in order to edit or add new -pages. +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. +.. _prose_docs: -Documentation -============= +Prose documentation +------------------- -The below table of contents lists all of Fabric's prose (non-API) -documentation, and is the best place to get started with using Fabric. See the -:ref:`api` and :ref:`contrib` sections for API 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: 3 + :maxdepth: 1 installation development usage compatibility -.. _api: +.. _api_docs: + +API documentation +----------------- -Core API -======== +Fabric maintains two sets of API documentation, autogenerated from the source +code's docstrings (which are typically very thorough.) -Below is Fabric's core API documentation, which is autogenerated from the -source code's docstrings (which are typically very thorough.) The core API is -loosely defined as those functions, classes and methods which form the basic -building blocks of the framework, such as `run` and `sudo`, used by fabfiles -and the below :ref:`contrib` codebase. +The **core** API is loosely defined as those functions, classes and methods +which form the basic building blocks of Fabric (such as `run` and `sudo`) upon +which everything else (the below "contrib" section, and user fabfiles) builds. .. toctree:: - :maxdepth: 3 + :maxdepth: 1 :glob: api/* - -.. _contrib: - -Contrib -======= - -Fabric's contrib package contains commonly useful tools (often merged in from -user fabfiles) for tasks such as user IO, 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 as more use-cases are solved and added. +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: 3 + :maxdepth: 1 :glob: contrib/* -Indices and tables -================== +Getting help +============ + +If you've scoured the :ref:`prose <prose_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. + +.. _bugs: + +Bugs/ticket tracker +------------------- -Sphinx's autogenerated index, module index and search page. +To file new bugs or search existing ones, you may visit Fabric's `Redmine +<http://redmine.org>`_ instance, located at `code.fabfile.org +<http://code.fabfile.org>`_. Due to issues with spam, you'll need to (quickly +and painlessly) register an account in order to post new tickets. + +Wiki +---- -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +There is an official Fabric `MoinMoin <http://moinmo.in>`_ wiki reachable at +`wiki.fabfile.org <http://wiki.fabfile.org>`_, although as of this writing its +usage patterns are still being worked out. Like the ticket tracker, spam has +forced us to put anti-spam measures up; the wiki has a simple, easy captcha in +place on the edit form. docs/index.rst d30bf418e06cee5b7743c670fbf74ff12d7fef80 Jeff Forcier jeff@bitprophet.org http://github.com/karmazilla/fabric/commit/672e1e45ce04ba74e6b5943376d83bf671da74f1 672e1e45ce04ba74e6b5943376d83bf671da74f1 2009-09-06T18:46:30-07:00 2009-09-06T18:46:30-07:00 Overhaul of README and docs index page re #17. bd5e36d8f35f06129f635d50997a3f5a143891f7 Jeff Forcier jeff@bitprophet.org