ReStructuredText for SQL?

Question

I am trying to use DocUtils and reStructuredText to comment on SQL code. I can make this work when I turn on the markup inside multi-line comments. Then I use - Some text :: to enter each block of code.

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

Here is 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 to restructure text. The syntax of internal hyperlinks will 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 docutils 0.10 0.9.