Thanks for opening a discussion on this timely topic. I think that Matthias is well aware of the benefits of the top-of-the-file tags over the doctest tags, and is adding doctest tags only when they are necessary (this is a lot of work for him). However, I do think that your points
(1) hide unnecessary details from all end users (2) make the public documentation cleaner (3) reduce the maintenance for modularization (4) be an easy paradigm for all developers (5) have a specific location for all relevant information regarding dependencies should be achieved with the doctest tags too. We may also introduce a block tag like ":: optional - sage.modules sage.rings.finite_rings" that applies to a block of lines. On Thursday, June 8, 2023 at 10:15:45 AM UTC+9 Travis Scrimshaw wrote: > Dear everyone, > I would first like to thank the people who are working to improve the > Sage development and build process. However, I am starting to become > concerned about what is being done about the modularization of SageMath. > Specifically, it is involving the patchbombs (e.g., > https://github.com/sagemath/sage/pull/35742) with labeling doctests that > nobody will actually maintain beyond possibly Matthias. Furthermore, the > large amount of optional labels, especially with no actual optional > packages, is starting to scare some users. I tell them they can ignore it, > but I feel that is not giving off a good impression. It is even more > confounding for people who are starting to develop (e.g., the GSoC > students). > > In short, the current approach to modularization and doctests does not > scale. I also feel the cost-benefit ratio is too high. > > I think we need a new approach, something that is both hidden from the > end-user (who will essentially never care about anything that is supposed > to be in the "standard" distribution of Sage) and allows developers much > more ease to actually develop (including Matthias who will largely be the > one who will have to fix these). > > My proposal is that we *only* have top-of-the-file indicators for > doctests unless there is a very compelling reason not to. That is, always do > > # sage.doctest: optional - sage.modules sage.rings.finite_rings > > at the beginning of files. This will hide what should be unnecessary > details from nearly all end users (for example, who really would not > install symbolics with Sage on a general install?), make the public > documentation cleaner, reduce the maintenance for modularization, be an > easy paradigm for all developers, and have a specific location for all > relevant information regarding dependencies. > > I think there is general consensus that we should make Sage better in > terms of being a distribution (albeit with some personal reservations with > ending up at the "grass is greener on the other side" feeling). Yet, I > really do not see the benefit to having such optional markings localized to > individual doctests, which often then have to propagate to subsequent ones. > > Best, > Travis > > -- 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 [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/sage-devel/82832aea-dbc2-4109-9e35-9aeebca2b8aen%40googlegroups.com.
