I think I'm finally starting to get this. sphinx-doc uses docutils to do most of its work. Docutils provides the parsing of rst along with pretty much all of the work that sphinx-doc does. So... it is indeed docutils that I need to work with to make this work.

On Sun, Dec 29, 2013 at 11:31 AM, Guenter Milde <milde@users.sf.net> wrote:
On 2013-12-29, Michael Lustfield wrote:
> This function now sticks things on the page, but... I can't figure out
> how to register a heading. The heading I want to register will always
> be the same level.

From the explanations further down, I suppose you want to add a heading
element to the document tree. In the docutils sources, there are examples
of both: directives that add more than one node to the document tree and
a directive that adds a heading node. The right combination of these
should do what you expect.

That sounds exactly like what I need (add heading node). I'm not finding any examples of doing that, though.
> I also need to figure out how to print that to the screen.

Do you mean the HTML/PDF/ODF or whatever output?  Once you have the
correct element node added to the document tree (at the right place),
conversion to the output format should be done by the writer without
further effort. This is the nice thing about the separation of parsing,
transforming and writing steps.

I guess I have this part figured out now. I'll probably be wrong, but I think I have it.

> A very basic example of what I'm trying to do is...

> .. mydirective:: fuzzy

>     A|b|c|d
>     wuzzy
>     was a
>     bear

> I would like to do two things with this directive. I first want the
> argument to generate a title and the first line to generate a table,
> followed by the remaining stuff.

> If I weren't making this directive, it would be something more like this...

> fuzzy
> ~~~~~

>========= =
> *Title 1* A
> *Title 2* b
> *Title 3* c
> *Title 4* d
>========= =

> wuzzy
> was a
> bear

> This is a grossly simplified version, but basically explains exactly what I
> need. I need to first, register that heading, then I need to generate a
> table.

> I really hope this makes sense. I'm struggling to explain it and really hope
> that someone can help me figure this out.

For me, a help in creating such directives was to re-create the intended
behaviour in rst (as you do above) and then have a look at the rst2pseudoxml
or rst2xml output to see what the relevant part of the document tree looks
like. Then I go to docutils/docutils/parsers/rst/directives and look for
examples to copy and paste and adapt.

That sounds like a scary trip. I'll try to run through there and figure it out.