substitution + sphinx interpreted text roles

[Mike Beachy]

Hi -

First I want to say thanks for Sphinx; it looks great and I think it
is going to become our default python documentation tool.

Now my request - I'd like to use substitutions to cut down on the
noise of :class:, :meth: etc. specifications, but I can't find any way
to use the sphinx roles in substitution definitions.

The simple rst file:
--------------------
|Structure| and |substructure|

.. |Structure| replace:: :class:`Structure`
.. |substructure| replace:: :sub:`Structure`
--------------------

Gives the following errors when processed with 'make html'.

/home/beachy/tmp/tmp/index.rst:3: (WARNING/2) Substitution definition
"Structure" empty or invalid.

.. |Structure| replace:: :class:`Structure`
/home/beachy/tmp/tmp/index.rst:1: (ERROR/3) Undefined substitution
referenced: "Structure".

The built-in 'sub' role works fine, the sphinx 'class' role does
nothing.

This is with Sphinx 0.6.1 and the current (sometime last week)
docutils snapshot.

I saw the thread at
http://groups.google.com/group/sphinx-dev/browse_frm/thread/0851d2bcca16350d/d91ffc7ea06b576d?#d91ffc7ea06b576d,
and am currently planning to use obj as my default role as a
workaround, but think I would prefer to just have the ability to
explicitly define these on a per-document basis.

I can file a bug if this is one or look into creating a patch if you
can point me to the right place. I got lost in a sea of state machines
when I briefly tried to debug.

Thanks,
Mike

[Csaba Hoch]

Mike Beachy wrote:
> Hi -
>
> First I want to say thanks for Sphinx; it looks great and I think it
> is going to become our default python documentation tool.
>
> Now my request - I'd like to use substitutions to cut down on the
> noise of :class:, :meth: etc. specifications, but I can't find any way
> to use the sphinx roles in substitution definitions.
>
> The simple rst file:
> --------------------
> |Structure| and |substructure|
>
> .. |Structure| replace:: :class:`Structure`
> .. |substructure| replace:: :sub:`Structure`
> --------------------

Hi,

I tried to do exactly this a few days ago, so I'd like to see this
feature work, as well!

I like Sphinx, too. Especially the "embeddability" of its structures
(code blocks can be embedded into bullet items etc.)

Csaba

[Georg Brandl]

Mike Beachy schrieb:

Thanks for the message! The problem is that the cross-reference node I
use for objects wasn't defined as an Inline node, and so got thrown out
of the substitution.

It's not fixed in 0.6 and trunk branches.

Georg

[Mike Beachy]

On Apr 28, 3:13 pm, Georg Brandl <ge...@python.org> wrote:
> Thanks for the message!  The problem is that the cross-reference node I
> use for objects wasn't defined as an Inline node, and so got thrown out
> of the substitution.
>
> It's not fixed in 0.6 and trunk branches.

Does this mean it is indeed a bug? Let me know if I need to file
something.

Mike

[Georg Brandl]

Mike Beachy schrieb:

Oops, that was meant to read "It's now fixed...". You don't need to file
anything anymore :)

Georg

[Mike Beachy]

On May 2, 1:55 pm, Georg Brandl <ge...@python.org> wrote:
> >> It's not fixed in 0.6 and trunk branches.
>

> Oops, that was meant to read "It's now fixed...".  You don't need to file
> anything anymore :)

Aha! I should've been able to guess that typo but was just horribly
confused. Thanks for your help.

Mike