Improved matrix documentation #1982
Conversation
emikelsons
force-pushed
the
DocImprovements
branch
4 times, most recently
from
818e781 to
61d0040
Compare
emikelsons
force-pushed
the
DocImprovements
branch
from
61d0040 to
f3a91a5
Compare
|
@fingolfin @emikelsons and I just finished working out a first draft. Please take a look. more than happy to discuss more. |
|
|
||
| It is also possible to create matrices (in a matrix space only) directly, without first | ||
| It is possible to create matrices directly, without first |
There was a problem hiding this comment.
Since matrices spaces are not mentioned anymore, this sentence needs to be adjusted?
There was a problem hiding this comment.
My intention was to point out that matrix spaces aren't always necessary. However, per your suggestion I have adjusted the text slightly
docs/src/matrix.md
Outdated
| [t + 1 t 1] | ||
| [ t^2 t t] | ||
| [ -2 t + 2 t^2 + t + 1] | ||
| julia> A = S([K(0) 2a + 3 a^2 + 1; a^2 - 2 a - 1 2a; a^2 + 3a + 1 2a K(1)]) |
There was a problem hiding this comment.
Maybe make this matrix space free?
There was a problem hiding this comment.
I have now completely separated out all matrix space examples and have added generic matrix examples, where necessary
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #1982 +/- ##
==========================================
- Coverage 88.34% 88.33% -0.01%
==========================================
Files 124 125 +1
Lines 31404 31416 +12
==========================================
+ Hits 27743 27752 +9
- Misses 3661 3664 +3 ☔ View full report in Codecov by Sentry. |
emikelsons
force-pushed
the
DocImprovements
branch
from
85ee498 to
154b6f4
Compare
docs/src/matrix.md
Outdated
| [ 2 3 1] | ||
| [ t t + 1 t + 2] | ||
| [-1 t^2 t^3] | ||
| ```@example |
There was a problem hiding this comment.
| ```@example | |
| ```jldoctest |
please use jldoctest instead of @example wherever possible. Examples will just bitrot, we won't notice that they are out of date and need an update. See e.g. Nemocas/Nemo.jl#1683
There was a problem hiding this comment.
I initially added them as jldoctests, but I was getting a doctest error, so I changed it to @example. I believe the error was due to the fact, that I call @docs for the same function in 2 different .md files, but the jldoctests were different
There was a problem hiding this comment.
Ah, that sound like a different problem I can help you with that maybe makes this issue go away.
You can only include each docstring once by default. If you want to include it multiple times, you need to add canoncial=false to all but one occurrence. See e.g. https://github.com/oscar-system/Oscar.jl/blob/ca6338cf6de3345876d1db317a3230dce15b7ab7/docs/src/LieTheory/root_systems.md?plain=1#L50
The one place without canonical=false is the one that is linked to if you have a [`weyl_group(::RootSystem)`](@ref) somewhere.
Could you try this and then revert the example blocks back to doctests?
There was a problem hiding this comment.
The doctests here are completely independent from all of this, as they are not part of the docstrings but just happen to be in the markdown file
There was a problem hiding this comment.
I have now reverted back to jldoctests with the inclusion of 'canonical=false'. Hopefully, the tests should pass now
emikelsons
force-pushed
the
DocImprovements
branch
from
154b6f4 to
cc64c43
Compare
Improved matrix documentation by splitting matrix.md into 3 disjoint files
Any suggestions on possible changes are welcome
This is addressing #1981