Some more documentation progress

[Jutho]

This includes a major restructuring (breaking down long pages into separate pages) and a complete rewrite of the Sector documentation. This could become the manual page for TensorKitSectors.jl in time, but for now I would still include it here.

By lack of a good Markdown formatter, I switched to breaking lines at natural places (end of sentence, subsentences, …), like one might do with LaTeX documents. Maybe that strategy can lead to clean git diffs in future (potentially smaller) doc changes, but I am open to other suggestions.

This would very much benefit from some proofreading by e.g. @borisdevos , @leburgel , @lkdvos .

[codecov]

Codecov Report

❌ Patch coverage is 0% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/tensors/linalg.jl	0.00%	2 Missing ⚠️

Files with missing lines	Coverage Δ
src/tensors/linalg.jl	66.96% <0.00%> (-15.64%)	⬇️

... and 39 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

After the build completes, the updated documentation will be available here

[Jutho]

Thanks for the heroic effort @borisdevos , I will try to process all these comments tomorrow.

[Jutho]

Also, any general comments? What do you think of the new structure of the manual? Is it an improvement?

[borisdevos]

It's a global improvement in my opinion. If I had to complain about some stylistic choice, there are certain paragraphs in the docs where a bunch of methods/properties are explained back-to-back, which can be bothersome to read through (although I don't know how often people really read paragraphs from start to finish and just ctrl+f words). In my opinion, one of the best-written parts is the fusion tree manipulations subsection, but maybe I'm just a big fan of lists.

Another small remark: some paragraphs in the category theory introduction are also tough to read because there's some inconsistency with the maths written within the paragraph; some of it is not in some latex equation environment. Not a huge gripe, since this part is optional to read.

But again, the pros outweigh these minor cons heavily, and the content remains rich and descriptive. I actually learnt/relearnt a lot going through the docs again 😄.

[lkdvos]

I tried briefly skimming through the updates to just give some global comments, since it is a bit hard to interleave these/not duplicate the things @borisdevos has already marked (Thanks for the huge amount of work @borisdevos !!!)
I can then read a bit more in detail once these comments have been incorporated.

Considering the markdown formatting, I have also been advocating to indeed use a more "LaTeX" style for line breaks as well.
The lack of good markdown formatter is one good argument, but I think it is incredibly hard to figure out what the actual git diff is if entire paragraphs have to be changed/reflowed due to the introduction of a single longer word.
Additionally, github suggestions in text like this also does not work very well with linebreak limits, so in the long run I would simply use the rule that for text, every sentence is on its own line.
I'm okay with splitting up longer sentences on multiple different lines, but in general it tends to be language-wise better to then simply split up the sentence itself to begin with...
Ideally, we should just at some point decide to do this and have a single PR that implements it everywhere, so we can then spot the git diffs more easily.

---

I definitely like the division in more subpages, large pages make it quite hard to quickly jump to the wanted sections and to lose track of what is going on!

One suggestion I have is about the order of these pages in the manual section.
I think the main thing that feels slightly off to me is having Vector Spaces before the symmetries and sectors, and only then proceeding to Graded Spaces.
I can see the appeal of introducing a number of methods and concepts without the burden of the symmetries, and I like that idea.
Currently however, I feel like the Vector Spaces section isn't really a simplification of the concepts, and is still rather mathematically inclined both in language and concepts.
It seems also like some of the methods that are mentioned there are somewhat hard to illustrate, mostly because ComplexSpace does not have enough structure to show what is going on or why we need these methods to begin with.
I think that since most of our language is still quite mathematical in that section, it might turn out to be easier in the long run to simply bite through the sour apple (😀) and merge graded spaces and vector spaces together, after introducing sectors and symmetries, and then going to fusion trees, and finally tensors and tensor manipulations.

[lkdvos]

I think I managed to resolve most of Boris' comments now, I wonder if it makes sense to simply go ahead and merge this in its current state. At least some of the sections that still refer to old factorization functions are now cleaned up, so we should put a little haste on this.