==================================
Welcome to Fabric's documentation!
==================================

This site covers **fab-classic**'s usage & API documentation. fab-classic is still usually
referred to as Fabric in the documentation, and it is still imported as ``fabric``.

The primary site is the GitHub project page: https://github.com/ploxiln/fab-classic/

For information about installing fab-classic: :doc:`installing`.


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.

.. toctree::
    :hidden:

    installing
    tutorial


.. _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/*

.. toctree::
    :maxdepth: 1

    troubleshooting
    faq


.. _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/*


Contributing & Running Tests
----------------------------

For advanced users & developers looking to help fix bugs or add new features.

.. toctree::

    running_tests
    old_changelog
