Vim ReStructureText Macros

This post is about a great new document generator call Sphinx. It was created with the goal of simplifying document creation for Python projects, but can be used for much more. Using a simple text mark-up called reStructuredText, it will output beautiful HTML and PDF documents such as books, manuals, journals, etc.

Writing reStructuredText is extremely easy, however there are a few tweaks we can add to Vim to make adding reStructureText mark-up easier than using MS Word.

An example of reStructuredText from docs.python.org is shown below:

**********************************
Brief Tour of the Standard Library
**********************************

.. _tut-os-interface:

Operating System Interface
==========================

The :mod:`os` module provides dozens of functions for interacting with the
operating system::

>>> import os
>>> os.system('time 0:02')
0
>>> os.getcwd()      # Return the current working directory
'C:\\Python26'
>>> os.chdir('/server/accesslogs')

Be sure to use the ``import os`` style instead of ``from os import *``.  This
will keep :func:`os.open` from shadowing the builtin :func:`open` function which
operates much differently.

Section Macros

You will notice there are a few simple ways to denote sections of text. The most basic method is to underline text to indicate the start of a new section or sub-section. Because this is such a common operation when writing reStructureText, we can easily simplify these steps using macros in the Vim text editor.

Simply add the following macros to your ~/.vimrc file to easily turn any line of text into a reStructuredText section heading.

" Restructured Text
" #########################
   " Ctrl-u 1:    underline Parts w/ #'s
   noremap  <C-u>1 yyPVr#yyjp
   inoremap <C-u>1 <esc>yyPVr#yyjpA
   " Ctrl-u 2:    underline Chapters w/ *'s
   noremap  <C-u>2 yyPVr*yyjp
   inoremap <C-u>2 <esc>yyPVr*yyjpA
   " Ctrl-u 3:    underline Section Level 1 w/ ='s
   noremap  <C-u>3 yypVr=
   inoremap <C-u>3 <esc>yypVr=A
   " Ctrl-u 4:    underline Section Level 2 w/ -'s
   noremap  <C-u>4 yypVr-
   inoremap <C-u>4 <esc>yypVr-A
   " Ctrl-u 5:    underline Section Level 3 w/ ^'s
   noremap  <C-u>5 yypVr^
   inoremap <C-u>5 <esc>yypVr^A

The macro's can be enabled with the following keypress: Control-U, #. '#' must be a number from 1-5. The numbering order of the macro's follow the Sphinx Section Heading mark-up definitions. For example the text 'MY SECTION HEADING', will be modified in the following manor for each macro.

Macro Shortcut	Final Output
Ctrl-U 1	################## MY SECTION HEADING ##################
Ctrl-U 2	****************** MY SECTION HEADING ******************
Ctrl-U 3	MY SECTION HEADING ==================
Ctrl-U 4	MY SECTION HEADING ------------------
Ctrl-U 5	MY SECTION HEADING ^^^^^^^^^^^^^^^^^^

Stay Tuned ...

In the future, I plan on adding any other useful Vim macros for reStructuredText at the end of this post.