sage.categories: Add `# optional` for modularization; reformat doctests #35422

mkoeppe · 2023-04-02T18:46:59Z

📚 Description

Adding doctest tags # optional - sage.rings.finite_rings, ...number_field, ...padics etc. for modularization purposes.

Also:

some coding style fixes in the doctests (such as adding spaces around some operators and after commas, following PEP 8)
improved the readability of doctests in the HTML format by breaking long lines to avoid having to scroll horizontally

This is:

Part of Meta-ticket: Modularize sagelib into separate distributions (pip-installable packages) sagemath-... for Sage 10.x #29705
Split out & squashed from Meta-PR: More # optional doctest tags #34998

📝 Checklist

The title is concise, informative, and self-explanatory.
The description explains in detail what this PR is about.
I have linked a relevant issue or discussion.
I have created tests covering the changes.
I have updated the documentation accordingly.

⌛ Dependencies

src/sage/categories/additive_magmas.py

src/sage/categories/category.py

tornaria · 2023-04-16T01:27:23Z

src/sage/categories/coxeter_groups.py

+                sage: W = CoxeterGroup('B3', implementation='coxeter3')     # optional - coxeter3
+                sage: b3_cells = W.kazhdan_lusztig_cells('two-sided')       # optional - coxeter3
+                sage: len(b3_cells)                                         # optional - coxeter3


What's the convention here, if not column 88?

This is an actual optional package; they should be aligned so that the tag is visible in full in the formatted doc.
My editor macro aligns these at column 64; but I think it's too hard (and not necessary) to make it globally consistent.

src/sage/categories/coxeter_groups.py

tornaria · 2023-04-16T01:37:44Z

src/sage/categories/enumerated_sets.py

@@ -494,7 +495,7 @@ def tuple(self):

            EXAMPLES::

-                sage: (GF(3)^2).tuple()
+                sage: (GF(3)^2).tuple()                                                 # optional - sage.libs.pari
                ((0, 0), (1, 0), (2, 0), (0, 1), (1, 1), (2, 1), (0, 2), (1, 2), (2, 2))


Maybe split this result so it fits in 80 columns? There are a few more below, some even a bit longer.

Column 80 plays no role in my undocumented style guide. I let the output run to column 86 regularly, and sporadically to column 96. (After that, horizontal scrolling is necessary.)

tornaria · 2023-04-16T01:42:24Z

src/sage/categories/filtered_modules_with_basis.py

+                Lazy family (Term map
+                 from Partitions
+                   to An example of a graded module with basis: the free module
+                      on partitions over Integer Ring(i))_{i in Partitions of the integer 4}


Maybe split one more line so it gets under 80 columns?
Let me try:

Suggested change

Lazy family (Term map

from Partitions

to An example of a graded module with basis: the free module

on partitions over Integer Ring(i))_{i in Partitions of the integer 4}

Lazy family (Term map

from Partitions

to An example of a graded module with basis:

the free module on partitions over Integer Ring(i)

)_{i in Partitions of the integer 4}

Not sure if that's actually ok... Your version is not so bad either, do as it pleases you.

My version runs to column 91, which I think is fine because there are no # optional tags around at column 88

Generally in reformatting doctest output, I don't introduce whitespace where no whitespace was before

tornaria · 2023-04-16T01:47:10Z

src/sage/categories/finite_complex_reflection_groups.py

@@ -56,15 +56,15 @@ class FiniteComplexReflectionGroups(CategoryWithAxiom):
        sage: W = ComplexReflectionGroups().Finite().example(); W       # optional - gap3


It seems the # optional - gap3 could all go in the same column for the whole file except for this line?

This one is at 72 (same as earlier up in the file). There are some occurrences around lines 900-1000 that I aligned at column 80 (rightmost place where the whole tag is visible) because the lines are longer. But in docstrings that have column-88 aligned tags, it has to be aligned farther to the left.

src/sage/categories/finite_dimensional_lie_algebras_with_basis.py

src/sage/categories/finite_dimensional_nilpotent_lie_algebras_with_basis.py

src/sage/categories/finitely_generated_lambda_bracket_algebras.py

src/sage/categories/finitely_generated_lie_conformal_algebras.py

tornaria · 2023-04-16T01:53:58Z

src/sage/categories/functor.pyx

@@ -477,7 +487,7 @@ class ForgetfulFunctor_generic(Functor):
        """
        TESTS::

-            sage: F = ForgetfulFunctor(FiniteFields(),Fields())
+            sage: F = ForgetfulFunctor(FiniteFields(), Fields())
            sage: F #indirect doctest
            The forgetful functor from Category of finite enumerated fields to Category of fields


want to split this output line?

In TESTS blocks, I have been less strict with the formatting because by default it is not shown in the formatted documentation.
Same for docstrings of private/special methods unless they appear in the formatted documentation

src/sage/categories/lambda_bracket_algebras_with_basis.py

Co-authored-by: Gonzalo Tornaría <tornaria@gmail.com>

…sis.py: Align # optional

Co-authored-by: Gonzalo Tornaría <tornaria@gmail.com>

SageMath version 10.0.rc0, Release Date: 2023-04-23

src/sage/categories/category.py

kwankyu · 2023-04-27T08:19:11Z

src/sage/categories/finite_dimensional_algebras_with_basis.py

+                sage: from sage.monoids.hecke_monoid import HeckeMonoid                 # optional - sage.groups
+                sage: A = HeckeMonoid(SymmetricGroup(4)).algebra(QQ)                    # optional - sage.groups sage.modules
+                sage: idempotents = A.orthogonal_idempotents_central_mod_radical()      # optional - sage.groups sage.modules sage.rings.number_field
+                sage: A.is_identity_decomposition_into_orthogonal_idempotents(idempotents)          # optional - sage.groups sage.modules sage.rings.number_field
                True


Why not align here?

No problem.

This super long identifier somehow stopped me from finding a better looking solution

kwankyu · 2023-04-27T09:08:11Z

src/sage/categories/lie_algebras.py

-                sage: L = LieAlgebras(QQ).example()
-                sage: L._test_distributivity()
+                sage: L = LieAlgebras(QQ).example()                                                                     # optional - sage.combinat sage.modules
+                sage: L._test_distributivity()                                                                          # optional - sage.combinat sage.modules



Isn't this too much far to the right?

Hmm. I see. This is aligned with other rows below.

And it's in a TESTS block of a private function, so it won't show in the HTML

kwankyu · 2023-04-27T09:32:28Z

src/sage/categories/vector_spaces.py

-                sage: W.dimension()
+                sage: M = FreeModule(FiniteField(19), 100)                              # optional - sage.libs.pari sage.modules
+                sage: W = M.submodule([M.gen(50)])                                      # optional - sage.libs.pari sage.modules
+                sage: W.dimension()                                                     # optional - sage.libs.pari sage.modules
                1


Isn't this sage.rings.finite_rings?

Indeed, thanks.

kwankyu · 2023-04-27T09:37:33Z

Otherwise, LGTM.

mkoeppe · 2023-04-27T23:49:34Z

Thanks for reviewing!

kwankyu

Thanks. Then this is good to go.

mkoeppe · 2023-04-28T18:12:29Z

Thank you!

…reformat_doctests

github-actions · 2023-05-18T01:59:22Z

Documentation preview for this PR is ready! 🎉
Built with commit: e02b79e

Matthias Koeppe added 6 commits April 15, 2023 16:33

sage.categories: Add # optional; doctest cosmetics

70acfc7

Fixups

1a22510

sage.categories: More # optional

0398033

sage.categories: Align # optional

831c754

Fixups

4de54cf

sage.categories: Fix/realign some # optional

7cb61c9