1

I'm using reStructuredText with epydoc. How can I have the text of an internal link different than the target of the link? I have:

:todo: Figure out the `Product.manufacturer` relationship in `Product`.

The Product link looks fine and links to the Product object. The Product.manufacturer link goes to the proper member variable, but instead of the text being Product.manufacturer, I'd like to just be manufacturer.

I know this can be done if I use epytext, but we'd like to stick with reStructuredText so that we can switch documentation generators later if we want to.

CaptainThrowup
  • 919
  • 1
  • 7
  • 15

1 Answers1

1

I'm not familiar with epydoc myself, but the normal reStructuredText way would be this:

`manufacturer <Product.manufacturer>`_

Or, with Sphinx,

:attribute:`manufacturer <Product.manufacturer>`

Considering that epydoc seems to have overridden the default role to provide links, it will be being left to it. However, this is the most likely to work:

:todo: Figure out the `manufacturer <Product.manufacturer>` relationship in `Product`.
Chris Morgan
  • 86,207
  • 24
  • 208
  • 215
  • Unfortunately this just points to the actual URL ../Product.manufacturer , rather than inserting the location of the page for this object – lost Feb 07 '13 at 12:21
  • @lost: are you doing this in plain reStructuredText, as `\`manufacturer \`_` (note the trailing underscore), or without the underscore (thus making it just being "the default role") with epydoc? The former will work as you describe, while it sounds like the latter should work. – Chris Morgan Feb 07 '13 at 18:24
  • Ah, I did it with the _, from epydoc. However in epydoc, writing `store()` just generates "store()" in the output (fixed-width font) and a "failed identifier crossreference target" warning for "store()<baseplot.BasePlot.store()>" – lost Feb 08 '13 at 14:43
  • gah it ate the backticks round the bit after "writing" – lost Feb 08 '13 at 14:44
  • Well, I don't know. When I was answering it, I was just saying that that's what reStructuredText does in all its native equivalents (and what other things like Sphinx do as a result). I don't *know* that it works in epydoc as I still have never used it. – Chris Morgan Feb 08 '13 at 16:53
  • As for backticks, in comments you can use a backslash: `\`\\`xyz\\`\`` is rendered as `\`xyz\``. In questions and answers its a different style that you need... and two different styles depending on whether it's rendered in the client (the live preview) or the server (when you save it). That sort of thing is part of the reason I strongly dislike Markdown when comparing it to reStructuredText: it lacks a specification and so there are all sorts of nasty corner cases, many incompatible between implementations such that text is badly rendered or some things become impossible. :-( – Chris Morgan Feb 08 '13 at 16:56