Would it be possible to filter out all these optional tags from the docs? Its a bit annoying and they don't really add anything.

Would it be possible to filter out all these optional tags from the docs?

That would be very useful for the PDF documentation because in that format, the comments wrap around.

For HTML, I want to keep them.

Its a bit annoying

I have aligned these annotations so that only a little bit (# option....) is visible in order to minimize annoyance.

and they don't really add anything.

They do add important information for users of the modularized distributions: They can see in the documentation what examples can be run when this or that is installed but other things aren't, so that they can avoid trial and error.

Moreover, annotations that refer to libraries, such as # optional - sage.libs.singular, also give attribution to where the functionality of this example is implemented.

Here in the case of sage.matroids, the annotations also give the reader a rough idea how examples are constructed (from graphs? from linear algebra over finite fields? from schemes?), and which parts of the functionality are graph-theoretic in nature.

Its a bit annoying

I have aligned these annotations so that only a little bit (# option....) is visible in order to minimize annoyance.

This is not really working for me.

and they don't really add anything.

They do add important information for users of the modularized distributions: They can see in the documentation what examples can be run when this or that is installed but other things aren't, so that they can avoid trial and error.

In my opinion this "# optional" tag is not self-explanatory enough to provide the information you describe. I agree that users might profit from this, but currently its too opaque. I propose we strip them for now, and if you think the information is worth it parse the optional tags and add a tiny notice "This example requires xyz and abc" at the end, with hyperlinks to xyz and abc.

(sorry for this somewhat off-topic discussion, but I think the representation of these optional tags should be discussed before adding even more to the docs.)

In my opinion this "# optional" tag is not self-explanatory enough to provide the information you describe. I agree that users might profit from this, but currently its too opaque.

Sure, documentation will be needed. It will be added in the documentation of sage.features and in the READMEs of the distributions. (See https://github.com/sagemath/sage/pull/35095/files for the new distributions.)

I propose we strip them for now, and if you think the information is worth it parse the optional tags and add a tiny notice

I don't plan to work on this

Based on https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-trim_doctest_flags and https://github.com/sphinx-doc/sphinx/blob/d3c91f951255c6729a53e38c895ddc0af036b5b9/sphinx/transforms/post_transforms/code.py#L82-L125 this shouldn't be that hard. Maybe

from sphinx.ext import doctest as sphinx_doctest
sphinx_doctest.doctestopt_re = re.compile(r'#\s*(doctest|optional):.+$', re.MULTILINE)
trim_doctest_flags = True

or overwriting TrimDoctestFlagsTransform

Thanks, I've added this info to:

• PDF documentation: Replace # optional by footnote symbols #35726

That we are adding these annotations is already documented in https://doc.sagemath.org/html/en/developer/packaging_sage_library.html#preparing-doctests

There's nothing that "needs work" here.

In my opinion this "# optional" tag is not self-explanatory enough to provide the information you describe. I agree that users might profit from this, but currently its too opaque.

Sure, documentation will be needed. It will be added in the documentation of sage.features

This is happening in #35749

The test failure in ell_rational_field is unrelated.

Documentation preview for this PR (built with commit 4d507c7) is ready! 🎉

Thank you! May I set to "positive review"?

Done.