reStructuredText for SQL?

Question

I am trying to use DocUtils and reStructuredText to comment SQL code. I can get this to work when I include the markup inside multi-line comments. I then use --Some text:: to introduce each block of code.

I cannot get internal hyperlinks to work. I would like to write -- .. Step1_: but the parser ignores this because of the leading comment. Using a multi-line style also fails. Is there a way to get this to work?

Here's an example:

/*
==========
this query
==========
:Author: Me

Outline
==========

- Create table 1

- Create table 2

- Output the result

*/

-- _Step1: build the table::

    create table table1

-- _Step2: use Step1_ to build table 2::

    create table table2

Answer 1

I use Sphinx for restructure text. The syntax for internal hyperlinks would be, for example,

.. step1:

.. code-block:: sql

   create table table1     

This is later text in which an internal hyperlink occurs. Note
the indention of create table table1. It is part
of the .. code-block:: sql directive, so it must be indented.
Now here comes the internal link. Please see :ref:`step1` as
to how to create the table.

Answer 2

code-block supported by docutils version 0.10 or may be 0.9.