typelevel
A new version of cats-infographic is created
I see the cats document https://typelevel.org/cats/typeclasses.html refers tpolecat/cats-infographic, which is outdated and no maintenance since 2018-09-10.
I have created a new version of cats-infographic: https://github.com/ShapelessCat/cats-infographic/tree/develop. I do this for two reasons:
-
Address the outdated and no maintenance issue.
-
The original tpolecat/cats-infographic created its diagram with OmniGraffle, which generates .graffle files. OmniGraffle is not free. I replicate @tpolecat's work with LaTeX, and update my version to describe the type class hierarchy of cats 2.9.0, cats-effect 3.4.4, and cats-mtl 1.3.0.
I think the core contributors and maintainers of cats can consider to replace the old version cats-infographic with my new version. However, since I'm not an experienced LaTeX user, I think my diagram is not fancy enough in some details, including the fonts. I hope people can help me to polish my work, and then https://typelevel.org/cats/typeclasses.html can use it. I created the diagram with https://www.mathcha.io/. People who want to contributes can load the cats-infographic.mathcha file with https://www.mathcha.io/, and edit the diagram directly. After editing people can generate .pdf with https://www.overleaf.com/.
Oh, I've just remembered that there's also a separate work on updating the typeclasses diagram: #4325. AFAIK, the work it that PR is based on the Mermaid tool. But it just for a record. I personally have no experience neither with Mermaid nor Latex so I have no preference on that.
I am in favor of Mermaid because Laika (which we use to render the site) will have built-in support for it in the near future. GitHub also renders Mermaid out-of-the-box.
- https://github.com/planet42/Laika/issues/331
Oh, I've just remembered that there's also a separate work on updating the typeclasses diagram: #4325. AFAIK, the work it that PR is based on the Mermaid tool. But it just for a record. I personally have no experience neither with Mermaid nor Latex so I have no preference on that.
@satorg Thanks! I just checked the PR you mentioned.
Honestly speaking, I think the current Mermaid based diagrams in that PR doesn't have a fancy view, especially when comparing them with the existing cats-infographic. One example is the third diagram of that PR: https://github.com/tsobako/cats/blob/patch-1/docs/typeclasses.md. If, after some tweak, the Mermaid based diagrams can have better views, I also have no preference. Actually, because of @armanbilge's explanation, I even prefer the Mermaid solution if the view of its output is good enough. I believe we shouldn't give up an existing good solution just because it is not the built-in.
@ShapelessCat thanks for your comments.
If, after some tweak, the Mermaid based diagrams can have better views
Can you describe in more detail how it can be improved? In fact, if you can comment on that PR it would be great. Thanks!
I believe we shouldn't give up an existing good solution just because it is not the built-in.
Sure, and thank you for all your effort you put into it – to me the rendered diagram you created looks way better comparing to what we have on the website published now. But I also like the idea of having all the docs gathered in one place because it makes easier to keep the docs up-to-date in the future.
@ShapelessCat thanks for your comments.
If, after some tweak, the Mermaid based diagrams can have better views
Can you describe in more detail how it can be improved? In fact, if you can comment on that PR it would be great. Thanks!
@armanbilge What I mean is I'm not sure if Mermaid has the expressiveness to control details and improve the view. I'd like to spend time on reading Mermaid document, and have a try.
One thing I think should be improved is the arrows in current #4325. I can see that currently almost all the arrows in #4325 are generated by specifying the from node and to node, and no control for details. This leads to all these arrows being curved arrows. It seems Mermaid doesn't try to generate straight line arrows automatically. Too many curved arrows are distractive, and they make the view messy. I think one of the root causes is no nodes layout detailed control in the current #4325 Mermaid source code. Before reading the Mermaid document, I'm not sure if Mermaid can do this. I'll have a try and I hope I can find a way to let Mermaid generate straight line arrows.
I copied the below diagram from #4325. You can see the curved arrows I mentioned, and you also can see why I said: when there are many nodes, too many curved arrows are distractive, and they make the view messy. Compare the below diagram with the corresponding part in cats-infographic can make things even clearer.
graph BT;
classDef core fill:#BBBBFF,stroke-width:2px,stroke:#000;
classDef coreImportant fill:#6666FF,stroke-width:2px,stroke:#000;
subgraph core
direction BT
id25(UnorderedFoldable):::core;
id26(UnorderedTraverse):::core;
id27(Invariant):::core;
id28(Foldable):::coreImportant;
id29(Functor):::coreImportant;
id30(Semigroupal):::core;
id31(Contravariant):::core;
id32(Reducible):::core;
id33(Traverse):::coreImportant;
id34(InvariantSemigroupal):::core;
id35(ContravariantSemigroupal):::core;
id36(NonEmptyTraverse):::core;
id37(Distributive):::core;
id38(Apply):::core;
id39(InvariantMonoidal):::core;
id40(CoflatMap):::core;
id41(FlatMap):::core;
id42(CommutativeApply):::core;
id43(Applicative):::coreImportant;
id44(ContravariantMonoidal):::core;
id45(Comonad):::core;
id46(CommutativeFlatMap):::core;
id47(Monad):::coreImportant;
id48(CommutativeApplicative):::core;
id49(ApplicativeError):::core;
id50(Bimonad):::core;
id51(CommutativeMonad):::core;
id52(MonadError):::core;
id53(SemigroupK):::core;
id56(NonEmptyAlternative):::core;
id54(MonoidK):::core;
id55(Alternative):::coreImportant;
id26-->id25;
id28-->id25;
id29-->id27;
id31-->id27;
id32-->id28;
id33-->id26;
id33-->id28;
id33-->id29;
id34-->id27;
id34-->id30;
id35-->id31;
id35-->id34;
id36-->id32;
id36-->id33;
id38-->id29;
id38-->id34;
id39-->id34;
id40-->id29;
id37-->id29;
id41-->id38;
id42-->id38;
id43-->id38;
id43-->id39;
id44-->id35;
id44-->id39;
id45-->id40;
id46-->id41;
id46-->id42;
id47-->id41;
id47-->id43;
id48-->id42;
id48-->id43;
id49-->id43;
id50-->id45;
id50-->id47;
id51-->id46;
id51-->id47;
id51-->id48;
id52-->id47;
id52-->id49;
id56-->id43;
id56-->id53;
id55-->id43;
id55-->id54;
id55-->id56;
id54-->id53;
end
@armanbilge I revisited this issue and still can't find a way to precisely control Mermaid's link layout. If this limitation persists, I believe the Mermaid version of the typeclass diagram cannot provide a clear and effective visualization as we expected.
I created the version I proposed with some free online LaTeX services, making it easy to reproduce and maintain—unlike the original version, which relies on OmniGraffle, a proprietary software. It has been two years, and there have been no updates to the typeclass diagram or a viable Mermaid replacement. The current typeclass diagram in the document is severely outdated.
Even if the Mermaid version could eventually become the ultimate solution, before this can be done, shouldn't we use an up-to-date typeclass diagram as a temporary solution, rather than keep current outdated version?
@ShapelessCat thanks for reviving this—I agree, if we cannot create a satisfactory visualization with Mermaid, then LaTeX is for sure better than OmniGraffle :)
@armanbilge I'll update my version this weekend and create a PR next week.
I finished the update: https://github.com/ShapelessCat/cats-infographic.
My last question: how can I update the cats doc?
## Type classes in Cats
<img src="https://cdn.rawgit.com/tpolecat/cats-infographic/master/cats.svg" alt="infographic" style="width: 100%;"/>
From [cats-infographic by @tpolecat](https://github.com/tpolecat/cats-infographic).
How can I replace this https://cdn.rawgit.com/tpolecat/cats-infographic/master/cats.svg with mine?\
Nice work!
I imagine could just replace the source with https://raw.githubusercontent.com/ShapelessCat/cats-infographic/9530fdf50f35db02f9b0ceb406120acfe599b7ac/cats-infographic.svg and then change the caption to reference your repo?
