On Mon, May 14, 2012 at 07:52:00AM +0200, Christian Stump wrote:
> Hugh and I are currently finalizing the QuiverMutationType and have
> the following problem: the file is organized similarly to CartanType,
> so we have a factory delegating the work to reducible or irreducible
> classes, or giving samples. In CartanType, we have a long docstring
(just to be precise: in cartan_type.py, not in CartanType)
> for the file and a shorter for the call method saying in the end "SEE
> ALSO: func:`~sage.combinat.root_system.cartan_type.CartanType`".
>
> But when I do
>
> sage: sage.combinat.root_system.cartan_type.CartanType?
>
> I get back exactly this docstring.
This "see also" is meant for someone looking up directly the
documentation of the __call__ method, say with:
sage: CartanType.__call__?
It just turns out that, for good or bad, the docstring of
CartanType.__call__ is appended by the documentation system upon
CartanType?, so that CartanType? *seemingly* refers to itself.
> 1. In which case do I actually see the docstring for the file itself?
sage.combinat.root_system.cartan_type?
> 2. Is it a bug that the CartanTypeFactory.call docstring is short
No
> and is again obtained when looking at the "see also" of itself?
In that case, it's a questionable feature of the doc system, but we
should not try to work around it.
> 3. What would be a proper way of organizing the documentation here?
It's not perfect as is, but that's ok. The only thing I am not so
happy with is that CartanType and CartanType_abstract are not merged
together, but that's because we want CartanType to also play the role
of a module for e.g. CartanType.sample().
By the way, note that, with the trick `CartanType.__doc__ = __doc__`,
there is no documentation duplication.
Cheers,
Nicolas
--
Nicolas M. Thiéry "Isil" <nthi...@users.sf.net>
http://Nicolas.Thiery.name/
--
You received this message because you are subscribed to the Google Groups
"sage-combinat-devel" group.
To post to this group, send email to sage-combinat-devel@googlegroups.com.
To unsubscribe from this group, send email to
sage-combinat-devel+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/sage-combinat-devel?hl=en.
