Rusty

Rusty is a collection of extensions (directives and roles) for Sphinx documentation framework. While the extensions are somewhat compatible with docutils, the usage of Sphinx is currently required.

This is document describes how to install and develop the rusty module. For the usage, select the extension of your choice from the feature listing below.

Features

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

rusty.exceltable
Creates table from selected part of the Excel -document. Requires xlrd -module.
rusty.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.
rusty.regxlist
Creates bullet list based on regular expression rule. Similar to rolelist directive.
rusty.rolelist
Creates the bullet list from all the entries of the selected role, with some additonal ways to custom the output.
rusty.xmltable
Creates RST table from XML-document and based on query. Requires BeautifulSoup -module.

Quick introduction

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

  1. Install setuptools:

    wget peak.telecommunity.com/dist/ez_setup.py
    sudo python ez_setup.py
    
  2. Install Rusty, Sphinx and additional modules:

    sudo easy_install -U rusty Sphinx BeautifulSoup xlrd
    
  3. Start new Sphinx powered documentation project or continue with existing documentation:

    sphinx-quicstart
    
  4. Configure rusty directive or role of your choice into Sphinx conf.py configuration file. See Features for available extensions.

    # Add ``rusty`` into extension list
    extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'rusty.includesh']
    
  5. Place directive/role in your document:

    My document
    ===========
    The contents of the setup script:
    
    .. includesh:: setup.sh
    
  6. Build the document:

    sphinx-build -b html doc dist/html
    
  7. That’s it!

Further information

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

Table Of Contents

Next topic

Changelog

This Page