Would it make sense to have a decorator for `_element_constructor_` that adds the doc to the `__init__` (or the class) docstring? For example, in LazySeriesRing:
@element_construction_doc def _element_constructor_(self, x=None, valuation=None, degree=None, constant=None, coefficients=None): ... Martin On Wednesday, 11 June 2025 at 02:04:11 UTC+2 tcsc...@gmail.com wrote: > Hi Martin, > Indeed this is a tricky issue because there are two competing forces: > > 1 - The construction of elements should lie with the elements, which would > be accessible via the published html doc and "elt?". > 2 - The parsing of input to pass to the element is done by the parent. > > From purely 1, it is clear where the examples are best: in the element > class-level docstring. However, this is not easy to access if you only have > the parent. Pure 2 says put sufficient examples in the parent class-level > docstring as having it in the _element_constructor_() makes it hidden > (which is the place for more technical information/tests). However, you > don't want to repeat stuff, so doing stuff to satisfy completely 1 and 2 > together is a maintenance burden. > > My typical approach is mostly putting a fair amount of examples in the > parent class-level docstring (usually at least one example showing the > different parts of the API) to get a sense of how to construct elements, > having some additional less-technical information in the element > class-level docstring, and all the technical stuff in the element's > __init__() and/or parent's _element_constructor_() docstrings. > > The other thing to consider is how you expect users to construct elements. > For the polynomial ring, once you have one example using the generator, it > is clear how it is expected to be used. Matrices partially does what I > would do, but it could have a few more examples (and/or reference Matrix()). > > Best, > Travis > > > On Tuesday, June 10, 2025 at 12:27:00 AM UTC+9 axio...@yahoo.de wrote: > >> Dear all, >> >> I am trying to understand how we want to document parents and elements. >> As an example, consider a user trying to construct a matrix or a polynomial >> as follows. >> >> sage: MatrixSpace? >> sage: PolynomialRing? >> >> yields the class docstring or the class factory, which indeed contains >> documentation on how to construct a MatrixSpace or PolynomialRing. >> Everything is looking fine here. So let's do that: >> >> sage: M = MatrixSpace(QQ, 3) >> sage: P.<x> = PolynomialRing(QQ) >> >> Now, how do we construct elements? I would expect that >> >> sage: M? >> sage: P? >> >> tells me that, but this is not the case. The former again gives the >> class docstring, the latter gives the Call docstring (which at least points >> to _element_constructor_). >> >> I cannot imagine that a user would actually get the idea of typing >> >> sage: M._element_constructor_? >> sage: P._element_constructor_? >> >> So I have the following questions: >> >> 1) is there an obvious way to obtain the documentation on how to create >> elements which I overlooked? >> 2) if not so, is there a way to improve the situation? >> >> In any case, I am guessing that for new structures, this information >> should still be provided in the _element_constructor_ method. >> >> Best wishes, >> >> Martin >> > -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To view this discussion visit https://groups.google.com/d/msgid/sage-devel/e7911bee-076d-4173-9009-70ae55be5667n%40googlegroups.com.
