RE: [DOC-SIG] Xrefs (was)Status of documentation effort?
---------- 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 _______________
Friedrich, Robin K writes: ...
.. [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?
Robin, Why not: .. [Party] in module: Dance.Disco.Party for module attributes, and require that the module name be fully qualified? Or that using just one name is searched for in "current package, global package" order (meaning the "current package" needs to be known, which is not unreasonable). Using slashes instead of dots is adding new & unnecessary syntax; dots work well in Python, and these are references to Python objects. Tools can use whatever internal representations are needed easily enough. We can generalize this a little by using the form: .. [name] in <namespace-type>[:] <namespace-name> The colon should be omitable (new word?!); some people may like it for presentation, but it carries no content. Identifying the footer line should be done only on the leading ".." and brackets around the name. <namespace-type> should allow checking the reference to be sure it matches what's found at the target; I expect "class", "module", and "package" might be usable. Perhaps allow "namespace" to signify an namespace of arbitrary type. Overall, this seems like a very reasonable notation. -Fred -- Fred L. Drake, Jr. fdrake@cnri.reston.va.us Corporation for National Research Initiatives 1895 Preston White Drive Reston, VA 20191-5434 _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________
participants (2)
-
Fred L. Drake -
Friedrich, Robin K