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