rusty.includesh – Include shell scripts in documentation

Platforms: Unix, Windows

Module extends the standard include directive by making it possible to include shell scripts into documents, while providing following features listed below. See Usage for detailed example how to use the extension.

Features

Format conversion

Given shell file is converted into RST format using following rules:

• Shell commands are turned into code-blocks, using bash highlight
• Comments are turned into RST format, allowing standard formating rules

Inclusion

Only partial inclusion is supported by providing options:

• start-after: text to find in the external data file Only the content after the first occurrence of the specified text will be included.
• end-before: text to find in the external data file Only the content before the first occurrence of the specified text (but after any after text) will be included.
• encoding: name of text encoding The text encoding of the external data file. Defaults to the document’s encoding (if specified).

Exclusion

Lines starting with double-comment character in shell file are skipped while converting to document

Note

• Configuration parameter file_insertion_enabled must not be disabled in order to use this directive.
• Do not put the inclusion flags (start-after, end-before) after the double-comment characters, as they won’t be recognized.

Usage

The usage of the extension can be described best by showing a real world example:

Software installation consists from several steps of shell commands - which are described in documentation, one by one. However, to prevent user to run same installation steps manually, one could create a complete shell script from the installations steps.

While easy-to-run script is nice, the user ends up running the script blindfolded - without actually knowing what is happening as part of the installation process. Thus, to increase the knowledge about the software, it would be good to have the actual steps documented as well. Having same steps duplicated in script and documents leads eventually in out-dated material.

This directive helps to get best parts from both: having up-to-date setup script AND documentation. By generating the documentation from the script - and here’s how:

Shell script: setup.sh

Consider having shell script, that is used for example as part of the installation process.

#!/bin/sh
##=============================================      
## This is a application installation
## script. The comments are formated using RST
##=============================================
# Installation consists from three phases:
#
# 1. Downloading files
# 2. Installation
# 3. Configuration
#
# Create temp directory
CDATE=$(date +%Y-%m-%d)
mkdir -P /tmp/$CDATE

# .. _clear_temp:
#
# In case of existing files, delete the temporary files first
rm -rf /tmp/$CDATA

# Download the package and locate it to ``temp`` directory.
# Finally, extract the package.
cd /tmp/$CDATE
wget http://server.com/downloads/package.tar.gz
tar -xzf package.tar.gz

# .. IMPORTANT::
#
#    In case of upgrade, :ref:`delete the temporary files <clear_temp>`.
#

# Open the config file in editor
vim /etc/application.conf

# Change the parameter ``listen_port`` if needed. The default value is: 8080:: 
#
#   listen_address = "0:0:0:0"
#   listen_port = 8080
#
# Start the service to verify the configuration is valid
service application start

## 

Document: document.rst

In the documentation, the shell script can be included as a part of the documentation, by using includesh directive. The path to script is relative to the document.

Installation of the application can be completed by running
shell script named ``setup.sh``::

  chmod +x setup.sh
  ./setup.sh

Alternatively, you can run each command manually:

.. includesh:: setup.sh


And you're down with installation. Next phase is to change
the configuration::

1. Place the initial configuration in ``/etc/app.conf``
2. Open the config in editor and change as needed::
  
     vim /etc/app.conf
     
     
   .. includesh:: app.conf
      :start-after: <changethese>
      :end-before:  </changethese>
      
      
3. After finished, start the service::
  
     /etc/init.d/app start
    

Output

When the document is processed, the output is shown as follows (compare the output with setup.sh script and document.rst):

Installation consists from three phases:

1. Downloading files
2. Installation
3. Configuration

Create temp directory

CDATE=$(date +%Y-%m-%d)
mkdir -P /tmp/$CDATE

In case of existing files, delete the temporary files first

rm -rf /tmp/$CDATA

Download the package and locate it to temp directory. Finally, extract the package.

cd /tmp/$CDATE
wget http://server.com/downloads/package.tar.gz
tar -xzf package.tar.gz

Important

In case of upgrade, delete the temporary files.

Open the config file in editor

vim /etc/application.conf

Change the parameter listen_port if needed. The default value is: 8080:

listen_address = "0:0:0:0"
listen_port = 8080

Start the service to verify the configuration is valid

service application start

Module in detail

This module provides the includesh directive. It is implemented by IncludeShellDirective class.

class rusty.includesh.IncludeShellDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

IncludeShellDirective implements the directive. The class is registered as a directive in rusty.includesh.setup()

class rusty.includesh.ShellConverter(script_path, encoding='utf-8', comment_character='#')

Converts shell script into another format - restructured documentation format in this case.

>>> sc = ShellConverter(script_path='/tmp/script.sh', comment_character='#')
>>> sc.to_rst(target_path='/tmp/script.output.rst')