hi all,
i've been using sphinx for awhile now to create documentation for an
open source project called pymel:
http://www.luma-pictures.com/tools/pymel/docs/1.0/index.html
i came from an epydoc background and while there are a lot of things
about sphinx that are superior -- searching, templating, appearance,
overall design -- there are several features of epydoc that i really
miss. the main one that comes up time and again is cross
referencing. sphinx is incredibly picky about how it finds objects
being crossed referenced. it is a major stumbling block for new
users, and a royal pain even for expert users.
take this scenario:
i have a package: "wardrobe"
several subpackages deep i have a class:
"wardrobe.clothes.pants.Jeans"
in wardrobe/clothes/__init__.py:
from pants import Jeans
i intend users of my package to refer to "Jeans" as
"wardrobe.clothes.Jeans" in their code. the subpackage "pants" is just
for internal organization. this is a pretty common scenario.
in my documentation, unless the current module is
"wardrobe.clothes.pants" i must refer to Jeans
as :class:`clothes.pants.Jeans`. but since i want users to be
familiar with the "approved" location for this class, i actually have
to do :class:`clothes.Jeans <clothes.pants.Jeans>`. Do that 100
times for 50 different objects in your documentation and you'll see
where my frustration is coming from.
it would be a huge time saver if sphinx performed a more thorough
search, so that I could write :class:`clothes.Pants`. or using
default_role='obj' simply write `clothes.Pants`.
a common point of confusion for new sphinx users is: clothes.Pants is
the location of a valid python object, why doesn't the cross reference
work?
to review: when you cross reference an object, sphinx searches in
this way (from the docs):
1. without any further qualification: `clothes.Pants`
2. with the current module name prepended: ex.
`wardrobe.clothes.Pants`
3. with the current module and class name (if any) prepended: N/A
however, what isn't clearly explained is that the objects will only be
found in the location where their __module__ attribute is set, so
"wardrobe.clothes.pants.Jeans" is the *only* valid way to refer to
Jeans, because this is where it was defined. this is a sane measure,
since many outside resources are brought into a project which can make
the search unwieldy and unpredictable.
there is a simple way to expand the search and keep it safe: allow
second tier matching against locations other than that set by
obj.__module__ as long as obj.__module__ is within the current module
so the search would be like this:
1. clothes.Pants exists in absolute location? no
1. clothes.Pants exists in other location? no
2. wardrobe.clothes.Pants exists in absolute location? no
2. wardrobe.clothes.Pants exists in other location? yes
wardrobe.clothes.Pants.__module__.startswith( 'wardrobe' )?
yes.
then we have found a valid cross reference.
i think this would be a safe way to extend the search, and relieve
documentation writers of a lot of extra headache. makes things easier
when refactoring too. epydoc worked this way and i never had any
complaints or problems with it finding unintended objects. thoughts?
-chad
--
You received this message because you are subscribed to the Google Groups
"sphinx-dev" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/sphinx-dev?hl=en.
