Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Add example to README, expand/update docs index.
  • Loading branch information
bitprophet committed Jul 5, 2009
1 parent adaf5ed commit a1ad6b2
Show file tree
Hide file tree
Showing 2 changed files with 61 additions and 9 deletions.
30 changes: 27 additions & 3 deletions README
Expand Up @@ -6,11 +6,35 @@ forth.

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. Fabric provides extra functionality related to this mode of use, such as
tool. For example, here's a small (but complete) ``fabfile.py`` 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)::

$ fab -H localhost,linuxbox uname
[localhost] run: uname -s
[localhost] out: Darwin
[linuxbox] run: uname -s
[linuxbox] out: Linux

Done.
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 API on top of SSH or SCP may import and utilize specific
pieces of functionality.
needing a simple but powerful API on top of SSH or SCP may import and utilize
specific pieces of functionality.
40 changes: 34 additions & 6 deletions docs/index.rst
Expand Up @@ -2,12 +2,18 @@
Fabric
======

Work in progress!
=================
Status
======

Fabric 0.9 is now in beta, meaning that its behavior and feature set are
effectively frozen. However, this documentation is still being expanded and
updated prior to final release, so changes are likely to occur.
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 (as well as the
test suite) 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.


About
Expand Down Expand Up @@ -51,6 +57,8 @@ The best way to get help with using Fabric is via the `fab-user mailing list
list contains an active community of other Fabric users and contributors as
well.

.. _bugs:

Bugs
----

Expand All @@ -76,6 +84,10 @@ reports, as an alternative to sending email.
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.

.. toctree::
:maxdepth: 3

Expand All @@ -84,9 +96,16 @@ Documentation
usage
compatibility

.. _api:

API
===
Core API
========

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.

.. toctree::
:maxdepth: 3
Expand All @@ -95,9 +114,16 @@ API
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.

.. toctree::
:maxdepth: 3
:glob:
Expand All @@ -108,6 +134,8 @@ Contrib
Indices and tables
==================

Sphinx's autogenerated index, module index and search page.

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

0 comments on commit a1ad6b2

Please sign in to comment.