======
Rusty
======
Rusty is a :ref:`collection of extensions (directives and roles) <features>`
for `Sphinx documentation framework <http://sphinx.pocoo.org/>`_. While
the extensions are somewhat compatible with `docutils`_,
the usage of *Sphinx is currently required*.

This is document describes :ref:`how to install <intro>` and :ref:`develop <further>`
the :mod:`rusty` module. For the usage, select the extension of your choice from the
:ref:`feature listing below <features>`.

.. _features:

Features
========
Following extensions are currently available in the Rusty module. The detailed usage
information for each extension are described in the subsections:

.. container:: exceltable

    :doc:`rusty.exceltable <exceltable>`
      Creates table from selected part of the Excel -document.
      Requires `xlrd`_ -module.

.. container:: includesh

    :doc:`rusty.includesh <includesh>`
      Extends the standard `include`_ directive
      by converting the given shell script file into RST format:
      comments are formatted into text and commands put in the code blocks.

.. container:: regxlist

    :doc:`rusty.regxlist <regxlist>`
      Creates bullet list based on :term:`regular expression <regexp>` rule.
      Similar to :doc:`rolelist directive <rolelist>`.

.. container:: rolelist

    :doc:`rusty.rolelist <rolelist>`
      Creates the bullet list from all the entries of the selected role,
      with some additonal ways to custom the output.

.. container:: xmltable

    :doc:`rusty.xmltable <xmltable>`
      Creates RST table from XML-document and based on query.
      Requires `BeautifulSoup`_ -module.


.. index:: Installation

.. _intro:

Quick introduction
==================
Here you can find the minimum steps for installation and usage of the module:

#. Install setuptools::

     wget peak.telecommunity.com/dist/ez_setup.py
     sudo python ez_setup.py

#. Install `Rusty <http://jmu.koodiorja.com/projects/rusty/>`_, `Sphinx`_ and
   additional modules::

     sudo easy_install -U rusty Sphinx BeautifulSoup xlrd

#. Start new Sphinx powered documentation project or continue with existing
   documentation::

     sphinx-quicstart

#. Configure rusty directive or role of your choice into Sphinx :file:`conf.py`
   configuration file. See :ref:`features` for available extensions.

   .. code-block:: python

     # Add ``rusty`` into extension list
     extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'rusty.includesh']

#. Place directive/role in your document:

   .. code-block:: rst

      My document
      ===========
      The contents of the setup script:

      .. includesh:: setup.sh

#. Build the document::

     sphinx-build -b html doc dist/html

#. That's it!

.. _further:

Further information
===================
Interested in module? See following sections for further information about it.

.. toctree::

   changelog
   devel
   faq
   glossary

.. toctree::
   :hidden:

   xmltable
   includesh
   global
   rolelist
   regxlist
   exceltable

.. include:: global.rst