-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Jacob Kaplan-Moss wrote: > ``:meth:`django.contrib.comments.models.Comment.save```
A nice simplification is if we could write `foo.bar.bam` without the leading :meth:, :attr: etc. Those prefixes are pretty much useless (and I have to keep the Sphinx web page open to look them up). The item being referenced is already unique - for example Comment.save wouldn't be both an attr and a meth. I just did a test changing :meth:`foo` to :attr:`foo` and the only difference is that sphinx didn't put () at the end of the link. Heck even :exc:`foo` worked. I'd suggest that either Sphinx start complaining about those (eg using :attr: to reference a method, :meth: to reference an exception) or that the prefixes be dropped (a default role can then lookup the referenced item and link to it appropriately based on type). As for the item being referenced (eg django.contrib.comments.models.Comment.save), only enough of it to be unambiguous is needed. For example if you only had one item named 'save' anywhere then you should just be able to write `save`. If there was more than one then `Comment.save` should be suitably unambiguous. The only remaining issue is if you want it expanded in the output text too. For example if you write: Then call `Comment.save` to start the tea. Do you want the output HTML text to read: Then call django.contrib.comments.models.Comment.save to start the tea. The current scheme of using a tilde (~) prefix should cover 99% of cases. Roger -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.9 (GNU/Linux) iEYEARECAAYFAkmjT1MACgkQmOOfHg372QSTLACg09nuPE+4KolBEcOgmFieHr0q PyoAniqmaHZVb7ZrbkQhQB7PyuK1PSAr =wFu1 -----END PGP SIGNATURE----- --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
