[DOC-SIG] Xrefs

[Robin Friedrich]

I really want to drive this markup to be as unobtrusive as possible to the doc
string reader. That's why we chose the footnote style rather than an in-line
markup scheme in the first place. If it's at all possible, I prefer the footnote
style.

Great ideals though. The Xref story so far... gendoc looks for words bounded by
[brackets] then adds this text to a dictionary as a key. At the end of the doc
string it looks for a line starting with two dots (.. ) and processes that line
to determine what that hyperlink refers to. (if there's not a matching label in
the footnotes then gendoc just leaves the bracketed text as is.)
So it might take the form:

.. [O'Reilly] http://www.oreilly.com/catalog/html2/index.html
for an ordinary URL, or:
.. [Wizbang] win32api:spamDialog.toolBar.wizBangPrime
for an external reference object called win32api, or:
.. [Geo-model] self.GeoPotentials.Model
to point to an object within our current package with an absolute path.
Since we mandate full pathing to python objects we don't need to specify what the
stating point of the reference is. Note also that the bracket highlighted text
does not have to correspond to the object it's pointing to.

The Wizbang example is cool in that gendoc could simply make a call to an
external object dictionary to ask for the reference information. For example:
w32 = get_doc_object_from_picklefile('whatever')
ExternalDocs = {'win32api': w32}
inserted_href =
ExternalDocs['win32api'].get_ref('spamDialog.toolBar.wizBangPrime')
to calculate the reference uri. This externalizes the smarts to anyone's own doc
network.

Boy this crossref stuff can get fun!

--
Robin K. Friedrich     Houston, Texas
  Python Professional Services, Inc.
      friedrich@pythonpros.com
     http://www.pythonpros.com



_______________
DOC-SIG  - SIG for the Python Documentation Project

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