Mixing live code and @RST

[wgw]

I think I am using @rst in an awkward way, and would appreciate a few
pointers.

To document live code with rst2, I used subheading in the code like
<<subroutine>> and then cloned that node and put it into the rst doc
tree.

That doesn't work anymore: <<nodes>> are not recognized by rst3, so
I'm converting those clones to "@rst-no-head label". In the the live
code I have to replace <<subroutine>> with @others. That's awkward at
times.

All this requires a bit of fiddling. Am I missing the point of rst3?
There must be a better way...

Any suggestions?

Thanks!

[Offray Vladimir Luna Cárdenas]

Hi,

Your idea of live code and @rst was also what I intended. In fact I
recently wrote a mail about the use of <<nodes>> markup to get live
documentation (inspired by the experience of Smalltalk). I don't know
why this feature was disabled (of if it was enabled at some point), but
this way of live docs would be a really helpful feature rooted on leo's
background and definitely would improve reading a lot.

Cheers,

Offray

[wgw]

Yes, the <<node>> in rst would be useful, for the same reasons it is
useful in code.

The work-around is to use an extra layer...

In live code:
<<Name>>
.....<<Name>> whose body has @others
................@rst-no-head Name .... whose body has the code

In an @rst tree:
first heading
next heading, which has at the end:
.. code-block::
.......@rst-no-head Name (cloned)

The terminal cloned node is inserted into the rst tree and the live
<<Name>> can be put properly into any place in the live code.

It isn't very convenient to have that extra level in live code, nor
having to put in the the cloned node as the last node of its parent.

What would be nice, is to allow within the @rst tree <<nodes>> that
mean just what they do in the live code: insert this text at the
indicated spot.

I'll bet it is no more than a tweak to add that functionality (since
it is done for the live code)... Then we could write:

In live code (as usual):
.
.
.
<<Name>>
.....<<Name>> .... whose body has the code

In an @rst tree:

heading
.. code-block::
<<Name>>
.......... <<Name>> (cloned node)
.
.

I will try to rummage around in the rst3 code and see if that is a
simple tweak.

On Oct 11, 1:41 pm, Offray Vladimir Luna Cárdenas <off...@riseup.net>
wrote:

[Edward K. Ream]

On Tue, Oct 11, 2011 at 10:57 AM, wgw <wgwi...@gmail.com> wrote:

> To document live code with rst2, I used subheading in the code like
> <<subroutine>> and then cloned that node and put it into the rst doc

> tree. [snip]

> Am I missing the point of rst3?

No. Adding what you want has been on the list a long time. I've just
moved it closer to the top of the list.

Edward

[wgw]

Thanks! I'm sure you have many wish list items to consider. Thank you for keeping all us clamouring users in mind.

[Edward K. Ream]

On Oct 11, 10:57 am, wgw <wgwin...@gmail.com> wrote:

> To document live code withrst2, I used subheading in the code like

> <<subroutine>> and then cloned that node and put it into the rst doc
> tree.

What you and I have both been missing is this:
http://webpages.charter.net/edreamleo/rstplugin3.html#section-expansion-options

This was added for Leo 4.9, but somehow an old to-do item didn't get
deleted, so I didn't remember that I had already added these features!

The docs say that the new features are experimental, so please
experiment and let me know how they work for you :-)

Edward

P.S. As of Leo 4.9, all the old "code mode" features are Easter
Eggs. That is, they are thoroughly deprecated and no longer
documented. However, they still exist for those who may have been
using them.

EKR

[wgw]

I tried it out with:

Test
.....@rst test.html
      which contains:
      This is a test (underlined)
      then the reference:
      <<test>>
...............<<test>>
                which contains: Here is some text.

In the top node Test I have:
@ @rst-options
expand_noweb_references=True
expand_noweb_recursively=True
show_headlines=False  (without this, the <<test>> headline becomes a section heading)
@c

It sort of works:
--------------------------------------------

This is a test

<<test>>Here is some text.

Here is some text.

--------------------------------------------

The reference <<test>> does not get erased, even if the definition actually gets inserted beside it. On the other hand, though I can suppress the headline of the definition with the rst option, the body of the definition gets inserted as a section anyway; definitions are not ignored by rst.

But now I can go see what happens in the code for debugging, since the option gives a pointer into the code.

Thanks!

[Edward K. Ream]

On Thu, Oct 13, 2011 at 1:33 AM, wgw <wgwi...@gmail.com> wrote:
> I tried it out with: [big snip]

> The reference <<test>> does not get erased, even if the definition actually
> gets inserted beside it. On the other hand, though I can suppress the
> headline of the definition with the rst option, the body of the definition
> gets inserted as a section anyway; definitions are not ignored by rst.
>
> But now I can go see what happens in the code for debugging, since the
> option gives a pointer into the code.

Thanks for this report. Feel free to commit changes if you like, or I
can make any changes you suggest.

Edward

[holge...@googlemail.com]

To spare someone unknown some time:

A node titled

@rst-code somename

will look strange in the treepane of a future source file. But those titles will not get included as source-code into the resulting source files.

So if you want to produce documentation in rst and write code side-by-side(like me) and are to dumb to see the obvious (like me):

- Hold your breath,

- insert a clone of your method/class/whatever into your rst-tree,

- start the title with "@rst-code" (yes, will change in the code-tree BUT does nothing there)

- start rst3 in the top node of your rst-tree.

- enjoy your beautiful documentation. 

Man, am I stupid.

Greetings,

Holger Schuh