Should be a way to create documentation aliases about twisted HOT 25 CLOSED

#!html
<pre>
Yeah, something like that sounds good.  

I'm assigning this to me... I'll try find some time to see
how easy/hard this is to do sometime in the next few days.

</pre>

#!html
<pre>
Some of the links to API documentation from
http://twistedmatrix.com/documents/howto/pb-usage link
to pages that return 404.

For example, the section that reads "First we look at
the server. This defines an Echoer class (derived from
pb.Root), with a method called remote_echo() ..." links
to
http://twistedmatrix.com/documents/TwistedDocs/current/api/public/twisted.spread.pb.Root.html
which is a 404.

WebCVS says that the source doc for this looks like:

&lt;p>First we look at the server. This defines an Echoer
class (derived from
&lt;code class="API"
base="twisted.spread">pb.Root&lt;/code>), with a method called
&lt;code>remote_echo()&lt;/code>.

Don't know enough Twisted to say whether this is a bug
in the docs or in Lore or whether the docs are out of date.

</pre>

#!html
<pre>
The pb.Root link is broken because Root is actually defined
in twisted/spread/flavors.py, and is merely imported by
pb.py, so epydoc doesn't document it.  Unfortunately,
typical use is to import it from pb, so the HOWTO is
correct.  I'm not sure what the right fix for this is.

(This is probably a good reason to avoid nasty "promotion"
hacks where a class is defined in one module, but only
documented publicly as available from another.  Yes, I'm
thinking about flow here ;)

</pre>

#!html
<pre>
so, you fixed the function thing already, right? then all
that's left is this "alias" thing.

Here are the ways I can think of fixing it.

 * Similar to my idea (that you didn't like) about the
function problem, we could have lore do a o =
namedObject(aliasname), then *actually* like to qual(o). I
know you don't like this.  :-)

 * Manually maintain a list of aliases for lore to look up
all api links in and replace.

 * Add more markup to allow the text of the link to be
different from the actual api link.

</pre>

#!html
<pre>
Yep, functions links are fixed (in CVS, anyway).

 * Yep, still don't like it, especially for such a minor bug.

 * Keeping an explicit list of aliases is pretty sucky, but
not as bad as your first suggestion :)

 * Yuck, I don't like the idea of markup for that.  What
about the print form -- epydoc can produce latex, so it
would be possible to make Lore link to API docs in print. 
But if the reader sees "pb.Root (page 434)" and then turns
to 434 and finds the documentation for the flavors module,
they'll be confused.

I think what the best solution would be is to mark the alias
in the *source*.  We should do this anyway; what if some
later maintainer deleted the "from flavors import Root" line
in pb.py because it wasn't needed by the code in pb.py
anymore?  There should be some sign in the source that a
variable is part of the public API of a module, even if it
is just an import from elsewhere.

If we did that, then we could fix epydoc, not Lore :)

This makes sense to me, because "pb.Root" is an API, and it
should appear in the API docs...

</pre>

#!html
<pre>
Soo... something like, in pb.py

from twisted.python.epysupport import alias
alias('twisted.spread.flavors.Root', 'twisted.spread.pb.Root')

or maybe 
alias(flavors.Root, 'twisted.spread.pb.Root')

or just
alias(flavors.Root) with a hack to look in the caller's
namespace to see which module he's coming from ;)

</pre>

#!html
<pre>
How's this going?

</pre>

#!html
<pre>
Itamar Shtull-Trauring &lt;itamar@...> added the comment:
> How's this going?

Still no progress, still haven't figured out how to continue.
</pre>

#!html
<pre>
So, we could just "fix" this with a nasty hack: just define a trivial subclass
in pb.py, e.g.:

    class Root(flavors.Root):
        pass

Actually, I guess the proposed alias function could do this... but working with
epydoc rather than hacking around it is probably a better idea.
</pre>

#!html
<pre>
I thought of this.
It bothered me because of persistence constraints.
</pre>

#!html
<pre>
At #38 this issue wins the prize for oldest unresolved bug ;)

If it's not gonna be fixed, can we just mark it done-cbb and move along?
</pre>

#!html
<pre>
It's not done at all, and it stil has to be fixed. :-(
</pre>

set(['Cacheable', 'portno', 'Copyable', 'RemoteReference', 'Viewable', 
'RemoteCache', 'authIdentity', 'ProtocolError', 'getObjectAt', 'ViewPoint',
'PBServerFactory', 'setUnjellyableForClass', 'Broker', 'Referenceable', 
'setCopierForClassTree', 'setCopierForClass', 'RemoteCopy', 'PBClientFactory', 
'Avatar', 'IPerspective', 'Root', 'failure2Copyable', 'DeadReferenceError', 
'BrokerFactory'])