[DOC-SIG] Xrefs (was)Status of documentation effort?

[Friedrich, Robin K]

>----------
>From: 	Mark Hammond[SMTP:MHammond@skippinet.com.au]
>But my main point of writing is to outline one of my key requirements before
>I could move to gendoc full-time.
>
>I really, really, really would like a technique for defining
>cross-references in the documentation strings.  At the moment URL's are OK,
>but it is nigh on impossible to have "func1" contain a documentation
>cross-reference to "func2" - there is no URL for "func2" - it is being
>generated by the same process doing func1.
Acknowledged. I'll add that to the list of requirements. 
>
>...Unfortunately, this is not as trivial as it sounds - but it is not too
>hard
>either.  Is there general support for a feature like this?
Not yet. We'll have to cook up one. I propose extending the footer
syntax (the one prefixed with two dots) to specify a cross-reference
token. Something like:
"""
I'm here in the middle of the doc string for class Fun but I would like
to mention that this class is used to populate the container class
[Party].  And at the end of the doc string...

.. [Party] in module: Disco
"""
In this case gendoc would look for documented object 'Party' in module
Disco. We'd have to have other context indicators like package and then
maybe bore down to the containing namespace by slash separated names,
e.g. 
.. [method] in package: Dance/Disco/Party

to completely specify the Party.method cross reference. A problem crops
up if you want to reference two objects of the same name in different
namespaces. Ideas?
>
>
>

_______________
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
_______________